Skip to content

Point documentation at docs.networktocode.com and fix site defects - #434

Open
jvanderaa wants to merge 1 commit into
developfrom
fix-425-docs-site
Open

Point documentation at docs.networktocode.com and fix site defects#434
jvanderaa wants to merge 1 commit into
developfrom
fix-425-docs-site

Conversation

@jvanderaa

Copy link
Copy Markdown
Contributor

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 under docs.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:

  • Broken header logo. The theme pointed at docs/assets/networktocode_logo.svg while the file lived in docs/images/, so the logo 404'd. Moved the file (theme chrome belongs in assets/; images/ is for content images embedded in pages).
  • "Edit this page" 404'd on every page. edit_uri was edit/main/circuit-maintenance-parser/docs; the default branch is develop and docs live at docs/.
  • The Code Reference was silently empty. generate_code_reference_pages.py globbed a circuit-maintenance-parser directory 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 existing mkdocs-gen-files — no new dependency.
  • Removed the unused site_dir, which wrote the built site into a Nautobot-app static/ path this library does not have.
  • Fixed a v2.10 release-note link that used underscores in the repo name.

mkdocstrings heading_level moves 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.lock is 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 python template in networktocode-llc/cookiecutter-ntc, which uses project_slug where project_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.

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Comment thread pyproject.toml
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/"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

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.

Read The Docs returning 404 error for project documentation

2 participants