Skip to content

docs: link the documentation site at the top of the README - #21

Merged
Akinzou merged 1 commit into
masterfrom
docs/readme-site-link
Nov 11, 2026
Merged

Akinzou merged 1 commit into
masterfrom
docs/readme-site-link

Conversation

@Akinzou

@Akinzou Akinzou commented Nov 11, 2026

Copy link
Copy Markdown
Owner

Moves the documentation site link from below the table of contents to right after the description, so it is the first thing a reader on GitHub or PyPI sees.

  • One sentence says the site follows master, while a PyPI release's README and the files it links match that release (ADR 0012).
  • Site root only, no deep links: a release's README stays on PyPI for good, /reference/-style paths are outside what mkdocs --strict checks, and a renamed section would turn them into permanent 404s.

Verification: pytest (387 passed), check_file_length.py, mkdocs build --strict, a dry run of pin_readme_links.py for v3.0.1 (31 links pinned), twine check --strict.

/code-review high: 5 findings. Fixed: the site links contradicting the release-pinning promise, the duplicated architecture/ADR links, and the deep links not covered by CI. Not changed: the Docs badge next to the callout, kept as the standard entry point (a URL change touches the badge, the callout and pyproject; accepted).

The link sat below the table of contents, where few readers get. It now
follows the description, with one sentence saying the site tracks master
while a PyPI release's README matches that release.

Chose the site root over deep links (/reference/, /adr/): a release's README
stays on PyPI for good, those paths sit outside what mkdocs --strict checks,
and a renamed section would turn them into permanent 404s.
@Akinzou
Akinzou merged commit 95b4a02 into master Nov 11, 2026
10 checks passed
@Akinzou
Akinzou deleted the docs/readme-site-link branch November 14, 2026 01:24
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