From a69f97a5302e2c35a42ffb0ffdfa3a3998ac6b6e Mon Sep 17 00:00:00 2001 From: Josh VanDeraa Date: Tue, 18 Aug 2026 08:54:14 -0500 Subject: [PATCH 1/2] Point documentation at docs.networktocode.com and fix site defects 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. --- .gitignore | 1 - README.md | 18 +++++++-------- changes/425.fixed | 1 + circuit_maintenance_parser/parsers/apple.py | 6 +---- circuit_maintenance_parser/parsers/equinix.py | 8 +++---- circuit_maintenance_parser/parsers/flag.py | 4 ++-- .../parsers/globalcloudxchange.py | 4 ++-- circuit_maintenance_parser/utils.py | 2 +- docs/admin/release_notes/version_2.10.md | 2 +- .../{images => assets}/networktocode_logo.svg | 0 docs/generate_code_reference_pages.py | 23 ++++++++----------- mkdocs.yml | 8 +++---- pyproject.toml | 4 ++-- 13 files changed, 36 insertions(+), 45 deletions(-) create mode 100644 changes/425.fixed rename docs/{images => assets}/networktocode_logo.svg (100%) diff --git a/.gitignore b/.gitignore index bb324eae..fabcfd8d 100644 --- a/.gitignore +++ b/.gitignore @@ -125,7 +125,6 @@ venv.bak/ # mkdocs documentation /site -/circuit-maintenance-parser/static/ # mypy .mypy_cache/ diff --git a/README.md b/README.md index ee5dcae2..f6e54c06 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@

- +

@@ -11,13 +11,13 @@ ## Documentation -Full documentation for this library can be found over on the [Circuit-Maintenance-Parser Docs](https://circuit-maintenance-parser.readthedocs.io/) website: +Full documentation for this library can be found over on the [Circuit-Maintenance-Parser Docs](https://docs.networktocode.com/projects/circuit-maintenance-parser/en/latest/) website: -- [User Guide](https://circuit-maintenance-parser.readthedocs.io/en/latest/user/lib_overview/) - Overview, Using the Library, Getting Started. -- [Administrator Guide](https://circuit-maintenance-parser.readthedocs.io/en/latest/admin/install/) - How to Install, Configure, Upgrade, or Uninstall the Library. -- [Developer Guide](https://circuit-maintenance-parser.readthedocs.io/en/latest/dev/contributing/) - Extending the Library, Code Reference, Contribution Guide. -- [Release Notes / Changelog](https://circuit-maintenance-parser.readthedocs.io/en/latest/admin/release_notes/). -- [Frequently Asked Questions](https://circuit-maintenance-parser.readthedocs.io/en/latest/user/faq/). +- [User Guide](https://docs.networktocode.com/projects/circuit-maintenance-parser/en/latest/user/lib_overview/) - Overview, Using the Library, Getting Started. +- [Administrator Guide](https://docs.networktocode.com/projects/circuit-maintenance-parser/en/latest/admin/install/) - How to Install, Configure, Upgrade, or Uninstall the Library. +- [Developer Guide](https://docs.networktocode.com/projects/circuit-maintenance-parser/en/latest/dev/contributing/) - Extending the Library, Code Reference, Contribution Guide. +- [Release Notes / Changelog](https://docs.networktocode.com/projects/circuit-maintenance-parser/en/latest/admin/release_notes/). +- [Frequently Asked Questions](https://docs.networktocode.com/projects/circuit-maintenance-parser/en/latest/user/faq/). ## Context @@ -307,11 +307,11 @@ The project is following Network to Code software development guidelines and is - Pylint for additional static analysis. - Unit and integration tests to ensure the library is working properly. -For more details, see the [Contributing Guide](https://circuit-maintenance-parser.readthedocs.io/en/latest/dev/contributing/) and [Development Environment Guide](https://circuit-maintenance-parser.readthedocs.io/en/latest/dev/dev_environment/). +For more details, see the [Contributing Guide](https://docs.networktocode.com/projects/circuit-maintenance-parser/en/latest/dev/contributing/) and [Development Environment Guide](https://docs.networktocode.com/projects/circuit-maintenance-parser/en/latest/dev/dev_environment/). ## Questions -For any questions or comments, please check the [FAQ](https://circuit-maintenance-parser.readthedocs.io/en/latest/user/faq/) first. Feel free to also swing by the [Network to Code Slack](https://networktocode.slack.com/) (channel `#networktocode`), sign up [here](http://slack.networktocode.com/) if you don't have an account. +For any questions or comments, please check the [FAQ](https://docs.networktocode.com/projects/circuit-maintenance-parser/en/latest/user/faq/) first. Feel free to also swing by the [Network to Code Slack](https://networktocode.slack.com/) (channel `#networktocode`), sign up [here](http://slack.networktocode.com/) if you don't have an account. ## License notes diff --git a/changes/425.fixed b/changes/425.fixed new file mode 100644 index 00000000..66626f54 --- /dev/null +++ b/changes/425.fixed @@ -0,0 +1 @@ +Fixed the documentation site: links now point to docs.networktocode.com instead of the retired Read the Docs Community project, the theme logo and page edit links resolve correctly, and the code reference pages are generated again. diff --git a/circuit_maintenance_parser/parsers/apple.py b/circuit_maintenance_parser/parsers/apple.py index e6081f37..6615f859 100644 --- a/circuit_maintenance_parser/parsers/apple.py +++ b/circuit_maintenance_parser/parsers/apple.py @@ -25,11 +25,7 @@ def parse_subject(self, subject: str) -> List[Dict]: class TextParserApple(Text): - """Parse the plaintext content of an Apple notification. - - Args: - Text (str): Plaintext message - """ + """Parse the plaintext content of an Apple notification.""" def parse_text(self, text: str) -> List[Dict]: """Extract attributes from an Apple notification email. diff --git a/circuit_maintenance_parser/parsers/equinix.py b/circuit_maintenance_parser/parsers/equinix.py index 6c1f7a8e..2677dd0a 100644 --- a/circuit_maintenance_parser/parsers/equinix.py +++ b/circuit_maintenance_parser/parsers/equinix.py @@ -146,10 +146,10 @@ def parse_subject(self, subject: str) -> List[Dict]: """Parse the Equinix Email subject for summary and status. Args: - subject (str): subject of email - e.g. 'COMPLETED - Remedial Emergency Maintenance - SG Metro Area Network Maintenance - 04-APR-2026 [CHG0124084]'. - alternative format: 'Service Impacting - Remedial - Dark Fiber Activity - SG Metro Area - Network Maintenance - 03-MAY-2026 - CHG0125903' - older format: 'Scheduled software upgrade in metro connect platform-SG Metro Area Network Maintenance -19-OCT-2021 [5-212760022356]' + subject (str): subject of email, in one of the following formats: + e.g. 'COMPLETED - Remedial Emergency Maintenance - SG Metro Area Network Maintenance - 04-APR-2026 [CHG0124084]'. + alternative format: 'Service Impacting - Remedial - Dark Fiber Activity - SG Metro Area - Network Maintenance - 03-MAY-2026 - CHG0125903' + older format: 'Scheduled software upgrade in metro connect platform-SG Metro Area Network Maintenance -19-OCT-2021 [5-212760022356]' Returns: diff --git a/circuit_maintenance_parser/parsers/flag.py b/circuit_maintenance_parser/parsers/flag.py index 0a8bf306..16dce53e 100644 --- a/circuit_maintenance_parser/parsers/flag.py +++ b/circuit_maintenance_parser/parsers/flag.py @@ -80,8 +80,8 @@ def parse_subject(self, subject: str) -> List[Dict]: """Parse the FLAG Email subject for maintenance ID and status. Args: - subject (str): subject of email - e.g. 'FLAG | PE2025102750538 | Planned Event | Rescheduled'. + subject (str): subject of email, + e.g. 'FLAG | PE2025102750538 | Planned Event | Rescheduled'. Returns: diff --git a/circuit_maintenance_parser/parsers/globalcloudxchange.py b/circuit_maintenance_parser/parsers/globalcloudxchange.py index c768f225..7feda4a8 100644 --- a/circuit_maintenance_parser/parsers/globalcloudxchange.py +++ b/circuit_maintenance_parser/parsers/globalcloudxchange.py @@ -51,8 +51,8 @@ def parse_subject(self, subject: str) -> List[Dict]: """Parse the Global Cloud Xchange Email subject for summary and status. Args: - subject (str): subject of email - e.g. 'PE2024020844407 | Emergency | Service Advisory Notice | Span Loss Rectification | 12-Feb-2024 09:00 (GMT) - 12-Feb-2024 17:00 (GMT)'. + subject (str): subject of email, + e.g. 'PE2024020844407 | Emergency | Service Advisory Notice | Span Loss Rectification | 12-Feb-2024 09:00 (GMT) - 12-Feb-2024 17:00 (GMT)'. Returns: diff --git a/circuit_maintenance_parser/utils.py b/circuit_maintenance_parser/utils.py index 9bb505cb..fc260ba2 100644 --- a/circuit_maintenance_parser/utils.py +++ b/circuit_maintenance_parser/utils.py @@ -132,7 +132,7 @@ def city_timezone(self, city: str) -> str: raise ParserError("Timezone resolution not properly initalized.") -def convert_timezone(time_str): +def convert_timezone(time_str) -> datetime.datetime: """ Converts a string representing a date/time in the format 'MM/DD/YY HH:MM Timezone' to a datetime object in UTC. diff --git a/docs/admin/release_notes/version_2.10.md b/docs/admin/release_notes/version_2.10.md index e0b2ea78..ca413cb9 100644 --- a/docs/admin/release_notes/version_2.10.md +++ b/docs/admin/release_notes/version_2.10.md @@ -12,7 +12,7 @@ This document describes all new features and changes in the `2.10` release serie - [#360](https://github.com/networktocode/circuit-maintenance-parser/issues/360) - Updated lxml to include version 6 - [#361](https://github.com/networktocode/circuit-maintenance-parser/issues/361) - Updated timezonefinder to v8.2.0 -- [#345](https://github.com/networktocode/circuit_maintenance_parser/issues/345) - Updated minimum Python version to 3.10 and upgraded dependencies including pytest (9.0), pylint (4.0), towncrier (25.8), backoff (2.2), and type stubs +- [#345](https://github.com/networktocode/circuit-maintenance-parser/issues/345) - Updated minimum Python version to 3.10 and upgraded dependencies including pytest (9.0), pylint (4.0), towncrier (25.8), backoff (2.2), and type stubs ### Housekeeping diff --git a/docs/images/networktocode_logo.svg b/docs/assets/networktocode_logo.svg similarity index 100% rename from docs/images/networktocode_logo.svg rename to docs/assets/networktocode_logo.svg diff --git a/docs/generate_code_reference_pages.py b/docs/generate_code_reference_pages.py index 0fed3899..e0cac4e5 100644 --- a/docs/generate_code_reference_pages.py +++ b/docs/generate_code_reference_pages.py @@ -1,20 +1,15 @@ -"""Generate code reference pages.""" +"""Generate the code reference page.""" from pathlib import Path import mkdocs_gen_files -for file_path in Path("circuit-maintenance-parser").rglob("*.py"): - module_path = file_path.with_suffix("") - doc_path = file_path.with_suffix(".md") - full_doc_path = Path("code-reference", doc_path) +PACKAGE = "circuit_maintenance_parser" - parts = list(module_path.parts) - if parts[-1] == "__init__": - parts = parts[:-1] - - with mkdocs_gen_files.open(full_doc_path, "w") as fd: - identifier = ".".join(parts) - 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: + print("# Code Reference\n", file=fd) + for file_path in sorted(Path(PACKAGE).rglob("*.py")): + parts = list(file_path.with_suffix("").parts) + if parts[-1] == "__init__": + parts = parts[:-1] + print(f"::: {'.'.join(parts)}", file=fd) diff --git a/mkdocs.yml b/mkdocs.yml index 798788f3..900b3a39 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,9 +1,8 @@ --- dev_addr: "127.0.0.1:8001" -edit_uri: "edit/main/circuit-maintenance-parser/docs" -site_dir: "circuit-maintenance-parser/static/circuit-maintenance-parser/docs" +edit_uri: "edit/develop/docs" site_name: "Circuit-Maintenance-Parser Documentation" -site_url: "https://circuit-maintenance-parser.readthedocs.io/en/latest/" +site_url: "https://docs.networktocode.com/projects/circuit-maintenance-parser/en/latest/" repo_url: "https://github.com/networktocode/circuit-maintenance-parser" copyright: "Copyright © The Authors" theme: @@ -107,7 +106,7 @@ plugins: python: paths: ["."] options: - heading_level: 1 + heading_level: 2 show_root_heading: true show_root_members_full_path: true show_source: false @@ -142,3 +141,4 @@ nav: - Development Environment: "dev/dev_environment.md" - Release Checklist: "dev/release_checklist.md" - Architecture Design Records: "dev/arch_decision.md" + - Code Reference: "code-reference.md" diff --git a/pyproject.toml b/pyproject.toml index 032824ae..c9a4d801 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,9 +4,9 @@ version = "2.12.1b1" description = "Python library to parse Circuit Maintenance notifications and return a structured data back" authors = ["Network to Code, LLC "] license = "Apache-2.0" -homepage = "https://circuit-maintenance-parser.readthedocs.io/" +homepage = "https://docs.networktocode.com/projects/circuit-maintenance-parser/en/latest/" repository = "https://github.com/networktocode/circuit-maintenance-parser" -documentation = "https://circuit-maintenance-parser.readthedocs.io/" +documentation = "https://docs.networktocode.com/projects/circuit-maintenance-parser/en/latest/" readme = "README.md" keywords = ["parser", "circuit", "maintenance"] classifiers = [ From 7248f1155b26bd3120984ea0ec8fb9861e455ed3 Mon Sep 17 00:00:00 2001 From: Josh VanDeraa Date: Fri, 18 Sep 2026 15:16:10 -0500 Subject: [PATCH 2/2] Leave the code reference generator unchanged Restore docs/generate_code_reference_pages.py to its current form and drop the Code Reference nav entry, narrowing this PR to the documentation link and site configuration fixes. Correcting the module path alone is not sufficient: mkdocs.yml has no nav entry for code-reference/, so the generated pages are not reachable and "mkdocs build --no-directory-urls --strict" aborts on the resulting warning. Handling the nav is tracked separately. --- changes/425.fixed | 2 +- docs/generate_code_reference_pages.py | 23 ++++++++++++++--------- mkdocs.yml | 3 +-- 3 files changed, 16 insertions(+), 12 deletions(-) diff --git a/changes/425.fixed b/changes/425.fixed index 66626f54..32f69922 100644 --- a/changes/425.fixed +++ b/changes/425.fixed @@ -1 +1 @@ -Fixed the documentation site: links now point to docs.networktocode.com instead of the retired Read the Docs Community project, the theme logo and page edit links resolve correctly, and the code reference pages are generated again. +Fixed the documentation site: links now point to docs.networktocode.com instead of the retired Read the Docs Community project, and the theme logo and page edit links resolve correctly. diff --git a/docs/generate_code_reference_pages.py b/docs/generate_code_reference_pages.py index e0cac4e5..0fed3899 100644 --- a/docs/generate_code_reference_pages.py +++ b/docs/generate_code_reference_pages.py @@ -1,15 +1,20 @@ -"""Generate the code reference page.""" +"""Generate code reference pages.""" from pathlib import Path import mkdocs_gen_files -PACKAGE = "circuit_maintenance_parser" +for file_path in Path("circuit-maintenance-parser").rglob("*.py"): + module_path = file_path.with_suffix("") + doc_path = file_path.with_suffix(".md") + full_doc_path = Path("code-reference", doc_path) -with mkdocs_gen_files.open("code-reference.md", "w") as fd: - print("# Code Reference\n", file=fd) - for file_path in sorted(Path(PACKAGE).rglob("*.py")): - parts = list(file_path.with_suffix("").parts) - if parts[-1] == "__init__": - parts = parts[:-1] - print(f"::: {'.'.join(parts)}", file=fd) + parts = list(module_path.parts) + if parts[-1] == "__init__": + parts = parts[:-1] + + with mkdocs_gen_files.open(full_doc_path, "w") as fd: + identifier = ".".join(parts) + print(f"::: {identifier}", file=fd) + + mkdocs_gen_files.set_edit_path(full_doc_path, file_path) diff --git a/mkdocs.yml b/mkdocs.yml index 900b3a39..e00ca3d3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -106,7 +106,7 @@ plugins: python: paths: ["."] options: - heading_level: 2 + heading_level: 1 show_root_heading: true show_root_members_full_path: true show_source: false @@ -141,4 +141,3 @@ nav: - Development Environment: "dev/dev_environment.md" - Release Checklist: "dev/release_checklist.md" - Architecture Design Records: "dev/arch_decision.md" - - Code Reference: "code-reference.md"