Point documentation at docs.networktocode.com and fix site defects - #434
Open
jvanderaa wants to merge 1 commit into
Open
Point documentation at docs.networktocode.com and fix site defects#434jvanderaa wants to merge 1 commit into
jvanderaa wants to merge 1 commit into
Conversation
The Read the Docs Community project was retired, so every documentation link in the README and package metadata returned a 404 (#425). Repoint them, and the mkdocs site_url, at the Read the Docs for Business site hosted under docs.networktocode.com. Also fixes several defects that made the site itself look broken, most of them cookiecutter leftovers that used the hyphenated project slug where the Python package name was required: - The theme logo pointed at docs/assets/networktocode_logo.svg while the file lived in docs/images/, so the header logo 404'd. Move the file. - edit_uri pointed at edit/main/circuit-maintenance-parser/docs, so the "edit this page" action 404'd on every page. Point it at edit/develop/docs. - generate_code_reference_pages.py globbed a "circuit-maintenance-parser" directory that does not exist, so the Code Reference the README advertises was silently empty. Glob the real package and render it as a single page under the Developer Guide, with no new dependency. - Drop the unused Nautobot-app site_dir, which wrote the built site into a static/ path this library does not have. - Fix a v2.10 release note link that used underscores in the repo name. mkdocstrings heading_level moves from 1 to 2 so that each module becomes a heading below the page title, which restores the in-page table of contents. Enabling the code reference surfaced seven griffe docstring warnings that fail the strict docs build; fix them at the source.
jvanderaa
requested review from
glennmatthews,
pke11y and
scetron
as code owners
August 19, 2026 14:50
| print(f"::: {identifier}", file=fd) | ||
|
|
||
| mkdocs_gen_files.set_edit_path(full_doc_path, file_path) | ||
| with mkdocs_gen_files.open("code-reference.md", "w") as fd: |
Contributor
There was a problem hiding this comment.
So this changes from a code-reference/ directory with one file per module into a single code-reference.md with all modules documented in a single file. Is that intentional/desirable?
| authors = ["Network to Code, LLC <opensource@networktocode.com>"] | ||
| license = "Apache-2.0" | ||
| homepage = "https://circuit-maintenance-parser.readthedocs.io/" | ||
| homepage = "https://docs.networktocode.com/projects/circuit-maintenance-parser/en/latest/" |
Contributor
There was a problem hiding this comment.
Do any of these fixes need to be additionally applied to the .cookiecutter.json file to make sure they don't get overwritten next time the package is rebaked?
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.
Fixes #425
The Read the Docs Community project was retired, so every documentation link in the README and package metadata returns a 404. This repoints them, and the mkdocs
site_url, at the Read the Docs for Business site underdocs.networktocode.com.A once-over of the site turned up several other defects, most of them cookiecutter leftovers that used the hyphenated project slug where the Python package name was required:
docs/assets/networktocode_logo.svgwhile the file lived indocs/images/, so the logo 404'd. Moved the file (theme chrome belongs inassets/;images/is for content images embedded in pages).edit_uriwasedit/main/circuit-maintenance-parser/docs; the default branch isdevelopand docs live atdocs/.generate_code_reference_pages.pyglobbed acircuit-maintenance-parserdirectory that does not exist, so the API docs the README advertises generated zero pages. It now globs the real package and renders as a single page under Developer Guide, using the existingmkdocs-gen-files— no new dependency.site_dir, which wrote the built site into a Nautobot-appstatic/path this library does not have.mkdocstrings
heading_levelmoves 1 → 2 so each module becomes a heading below the page title, which restores the in-page table of contents.Enabling the code reference surfaced seven griffe docstring warnings that fail the strict docs build; these are fixed at the source.
poetry.lockis unchanged — this PR adds no dependencies.Note: this does not by itself make the docs reachable
The Read the Docs for Business subproject still needs to be marked public by an admin. Until that happens,
docs.networktocode.com/projects/circuit-maintenance-parser/redirects to a login and the README docs badge reads "unknown".Upstream follow-up
Four of these defects come from the
pythontemplate innetworktocode-llc/cookiecutter-ntc, which usesproject_slugwhereproject_python_name(or a plain path) is required. Any repo generated from it likely has the same empty Code Reference and dead documentation links. Worth fixing upstream separately.