Skip to content

docs: fix all Sphinx documentation warnings#778

Merged
gijzelaerr merged 1 commit into
masterfrom
fix/doc-warnings
Jul 17, 2026
Merged

docs: fix all Sphinx documentation warnings#778
gijzelaerr merged 1 commit into
masterfrom
fix/doc-warnings

Conversation

@gijzelaerr

Copy link
Copy Markdown
Owner

Summary

  • Add sphinx.ext.intersphinx with Python docs mapping to resolve ~110 stdlib type warnings (datetime.datetime, pathlib.Path, socket.socket, logging.Logger, struct, etc.)
  • Add nitpick_ignore for ctypes types that intersphinx can't resolve (ctypes.Array, ctypes.c_int, ctypes.c_uint, snap7.type.S7DataItem, snap7.type.c_ubyte_Array_65536)
  • Add missing doc/API/error.rst and include it in the index, so cross-references to S7ProtocolError, S7ConnectionError, etc. resolve
  • Fix malformed multi-line Raises sections in set_fstring and set_string (continuation lines were parsed as separate exception types)
  • Qualify cross-references: Tag~snap7.tags.Tag, BlocksList~snap7.type.BlocksList, TS7BlockInfo~snap7.type.TS7BlockInfo, exceptions → ~snap7.error.*
  • Replace unresolvable :class:s7.Client / `:class:`s7.Server / :class:s7.AsyncClient`` with code literals (the s7 package isn't in the Sphinx docs)
  • Replace unresolvable :meth: references in s7commplus docstrings with code literals

Before: 139 warnings. After: 0 warnings. Build passes with sphinx-build -W -n.

Test plan

  • sphinx-build -W -n -bhtml doc/ doc/_build succeeds with 0 warnings
  • uv run pre-commit run --all-files passes
  • No new mypy errors introduced

🤖 Generated with Claude Code

Add intersphinx mapping for Python stdlib cross-references and
nitpick_ignore for unresolvable ctypes types. Fix malformed Raises
sections in setters.py, qualify cross-references to Tag, BlocksList,
TS7BlockInfo, and exception classes, and add missing error module
to the API docs.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@gijzelaerr
gijzelaerr merged commit dce204d into master Jul 17, 2026
39 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant