Skip to content

docs: give the Quickstart and Changelog nav entries real pages - #521

Open
roshaninfordham wants to merge 1 commit into
roboflow:mainfrom
roshaninfordham:fix/docs-nav-404
Open

docs: give the Quickstart and Changelog nav entries real pages#521
roshaninfordham wants to merge 1 commit into
roboflow:mainfrom
roshaninfordham:fix/docs-nav-404

Conversation

@roshaninfordham

Copy link
Copy Markdown

Description

Closes #380.

mkdocs.yml listed two nav entries whose files do not exist under docs/:

nav:
  - Quickstart: quickstart.md      # docs/quickstart.md never existed
  ...
  - Changelog: changelog.md        # docs/changelog.md never existed

docs/ contains only index.md, core/, models/ and styles.css, so both sidebar links published as 404s. mkdocs says so on every build:

WARNING - A reference to 'quickstart.md' is included in the 'nav' configuration, which is not found in the documentation files.
WARNING - A reference to 'changelog.md' is included in the 'nav' configuration, which is not found in the documentation files.

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 through pymdownx.snippets. The section is delimited in README.md with --8<-- [start:quickstart] / [end:quickstart] HTML comments, which render as nothing on GitHub.
  • docs/changelog.md — includes the root CHANGELOG.md the same way.
  • mkdocs.yml — enable pymdownx.snippets with base_path: ['.'] and check_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.md is already a copy of README.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

  • I have tested this code locally
  • All new and existing tests pass
mkdocs build     before: 50 warnings, including the two above
mkdocs build     after:  48 warnings, neither of the two present

The 48 remaining warnings are pre-existing griffe docstring warnings in roboflow/core/ and roboflow/models/, untouched by this change.

Rendered output checked, not just the build exit code: site/quickstart/index.html contains the Quickstart body, and site/changelog/index.html contains the changelog entries.

python -m unittest    970 tests, OK (skipped=1)   — unchanged from before the edit
ruff check .          All checks passed!

ruff format --check reports 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.

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.
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.

Docs Quickstart 404 error

1 participant