docs: modernize Sphinx config and fix broken cross-references - #74
Merged
Conversation
Bring the docs build up to current Sphinx conventions and repair
cross-references that were silently rendering as dead text.
conf.py:
- Enable sphinx.ext.intersphinx with python + sqlalchemy (2.0) mappings
so :class:`~sqlalchemy...` references resolve to upstream docs.
- Drop the legacy sys.path.insert hack (AutoAPI reads ../src statically).
- Remove unused sphinx.ext.autodoc (AutoAPI is standalone).
- Fold the extensions.append('autoapi.extension') into the extensions list.
- Auto-update the copyright year instead of freezing it at 2022.
- Prune AutoAPI options that only restated defaults; keep autoapi_root='api'
to preserve the published API URLs.
Also:
- Bump docs sphinx floor to >=8.0.
- Fix broken :class:/:meth: cross-references in async.rst and the aio.py
module docstring (AutoAPI registers classes at their source module path).
- Add docs/_static/.gitkeep to silence the missing-static-path warning.
Verified with `sphinx -b html -n -W` (nitpicky, warnings-as-errors): exit 0,
every cross-reference resolves.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Brings the Sphinx docs build up to current conventions and repairs cross-references that were silently rendering as dead text (Sphinx doesn't warn about unresolved refs outside nitpicky mode).
docs/conf.pysphinx.ext.intersphinxwithpython+sqlalchemy(2.0) mappings — the async docs already used:class:~sqlalchemy.ext.asyncio.AsyncSession`` and similar refs that linked nowhere. They now link to the real upstream docs.sys.path.insert(os.path.abspath('.'))hack (AutoAPI reads../srcstatically; nothing to import).sphinx.ext.autodoc(AutoAPI is standalone).extensions.append('autoapi.extension')into theextensionslist.copyrightyear instead of freezing it at2022.autoapi_root='api'(its default isautoapi, so dropping it would move the published API URLs and break inbound links).Other
docs/requirements.txt: bump the Sphinx floor>=4.3→>=8.0.docs/async.rst: fix 3 broken:class:/:meth:cross-references (AutoAPI registers classes at their source-module path, e.g.sqlalchemyseed.seeder.Seeder).src/sqlalchemyseed/aio.py: fix the one broken:meth:ref in the module docstring (rendered by AutoAPI).docs/_static/.gitkeep: added — removes the only warning in the original build (html_static_path entry '_static' does not exist).Verification
Built with
sphinx -b html -n -W(nitpicky + warnings-as-errors): exit 0 — every cross-reference resolves. Confirmed the rendered HTML emits real links:AsyncSession/run_sync→docs.sqlalchemy.org/en/20/…, andSeeder→ the internal API page.No
pyproject.toml/lockfile changes; runtime behavior is unchanged (the onlysrc/edit is a docstring).🤖 Generated with Claude Code