docs: give the Quickstart and Changelog nav entries real pages - #521
Open
roshaninfordham wants to merge 1 commit into
Open
docs: give the Quickstart and Changelog nav entries real pages#521roshaninfordham wants to merge 1 commit into
roshaninfordham wants to merge 1 commit into
Conversation
Both entries in mkdocs.yml pointed at files that do not exist under docs/, so the published sidebar linked to two 404s. Rather than duplicate content, both pages now single-source from files that already exist. quickstart.md pulls the README's Quickstart section through pymdownx.snippets, and changelog.md includes the root CHANGELOG.md, so neither can drift from the canonical copy.
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
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.
Description
Closes #380.
mkdocs.ymllisted two nav entries whose files do not exist underdocs/:docs/contains onlyindex.md,core/,models/andstyles.css, so both sidebar links published as 404s. mkdocs says so on every build:Both pages now exist and pull their content from the canonical copy that already lives in the repository, so neither can drift.
Changes Made
docs/quickstart.md— includes the README's Quickstart section throughpymdownx.snippets. The section is delimited inREADME.mdwith--8<-- [start:quickstart]/[end:quickstart]HTML comments, which render as nothing on GitHub.docs/changelog.md— includes the rootCHANGELOG.mdthe same way.mkdocs.yml— enablepymdownx.snippetswithbase_path: ['.']andcheck_paths: true, so a future missing include fails the build rather than rendering an empty page.I chose includes over new hand-written pages because
docs/index.mdis already a copy ofREADME.md; a third copy of the quickstart would be one more thing to keep in sync. The nav entry could also simply have been deleted, but a Python SDK reasonably has a Quickstart in its sidebar, and the content already existed — it just was not reachable.Testing
The 48 remaining warnings are pre-existing
griffedocstring warnings inroboflow/core/androboflow/models/, untouched by this change.Rendered output checked, not just the build exit code:
site/quickstart/index.htmlcontains the Quickstart body, andsite/changelog/index.htmlcontains the changelog entries.ruff format --checkreports 3 files (CONTRIBUTING.md,README.md,docs/index.md); it reports the same 3 on the parent commit, so that drift is pre-existing and not introduced here. The two files this PR adds both pass.Google Colab (optional)
Not applicable; documentation build change.