nox -e serve_docs shows several problems. #2606

Open
opened 2026-04-03 19:25:25 +00:00 by brent.edwards · 4 comments
Member

Metadata

  • Commit Message: fix(docs): resolve mkdocs serve_docs build issues
  • Branch: fix/m3-docs-build-issues

Background and Context

The nox -e serve_docs command produces several warnings and issues that need to be addressed to maintain a clean build process and comprehensive documentation coverage.

Current Behavior

When running nox -e serve_docs, the following problems occur:

  1. MkDocs 2.0 compatibility warning: Material for MkDocs displays a warning about MkDocs 2.0 breaking changes and recommends switching to ProperDocs.
  2. Missing nav entries: The following pages exist in the docs directory but are not included in the nav configuration:
    • development/custom_sandbox_strategy.md
    • reference/cloud_resources.md
    • reference/database_handler.md
    • reference/persona.md
    • reference/scaling_baselines.md
    • reference/tui.md
    • reference/tui_permission_question.md
    • reference/tui_permissions.md
    • reference/tui_shell_safety.md
    • reference/tui_thought_block.md
    • reference/uko_layer2_paradigm_vocabularies.md
    • reference/uko_layer3_technology_vocabularies.md
    • reference/uko_runtime.md
  3. Broken link: Doc file api/a2a.md contains a link ../../CHANGELOG.md, but the target ../CHANGELOG.md is not found.
  4. Type annotation warnings: Griffe (documentation generator) produces warnings about missing type annotations and parameter documentation in src/cleveragents/acms/uko/vocabularies.py and src/cleveragents/cli/commands/_resolve_actor.py.

Expected Behavior

Running nox -e serve_docs should:

  • Build the documentation without any MkDocs 2.0 compatibility warnings
  • Include all pages in the docs directory within the navigation configuration
  • Have all links working correctly
  • Generate documentation with no parameter type annotation warnings

Acceptance Criteria

  • MkDocs 2.0 warning is resolved (either by switching to ProperDocs or disabling the warning)
  • All documentation pages are reachable through the nav configuration
  • All links in documentation files resolve correctly
  • No type annotation warnings are produced during documentation generation

Subtasks

  • Resolve MkDocs 2.0 compatibility issue (switch to ProperDocs or address warning)
  • Add missing documentation pages to the nav configuration in mkdocs.yml
  • Fix broken link in api/a2a.md referencing CHANGELOG.md
  • Add missing type annotations in vocabularies.py and _resolve_actor.py
  • Tests: Verify all documentation builds cleanly with nox -e serve_docs
  • Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

  • All subtasks above are completed and checked off.
  • A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly (fix(docs): resolve mkdocs serve_docs build issues), followed by a blank line, then additional lines providing implementation details.
  • The commit is pushed to the remote on the branch matching the Branch in Metadata exactly (fix/m3-docs-build-issues).
  • The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
  • Running nox -e serve_docs produces clean output with no warnings related to the items above.
## Metadata - **Commit Message**: `fix(docs): resolve mkdocs serve_docs build issues` - **Branch**: `fix/m3-docs-build-issues` ## Background and Context The `nox -e serve_docs` command produces several warnings and issues that need to be addressed to maintain a clean build process and comprehensive documentation coverage. ## Current Behavior When running `nox -e serve_docs`, the following problems occur: 1. MkDocs 2.0 compatibility warning: Material for MkDocs displays a warning about MkDocs 2.0 breaking changes and recommends switching to ProperDocs. 2. Missing nav entries: The following pages exist in the `docs` directory but are not included in the `nav` configuration: - `development/custom_sandbox_strategy.md` - `reference/cloud_resources.md` - `reference/database_handler.md` - `reference/persona.md` - `reference/scaling_baselines.md` - `reference/tui.md` - `reference/tui_permission_question.md` - `reference/tui_permissions.md` - `reference/tui_shell_safety.md` - `reference/tui_thought_block.md` - `reference/uko_layer2_paradigm_vocabularies.md` - `reference/uko_layer3_technology_vocabularies.md` - `reference/uko_runtime.md` 3. Broken link: Doc file `api/a2a.md` contains a link `../../CHANGELOG.md`, but the target `../CHANGELOG.md` is not found. 4. Type annotation warnings: Griffe (documentation generator) produces warnings about missing type annotations and parameter documentation in `src/cleveragents/acms/uko/vocabularies.py` and `src/cleveragents/cli/commands/_resolve_actor.py`. ## Expected Behavior Running `nox -e serve_docs` should: - Build the documentation without any MkDocs 2.0 compatibility warnings - Include all pages in the `docs` directory within the navigation configuration - Have all links working correctly - Generate documentation with no parameter type annotation warnings ## Acceptance Criteria - [ ] MkDocs 2.0 warning is resolved (either by switching to ProperDocs or disabling the warning) - [ ] All documentation pages are reachable through the `nav` configuration - [ ] All links in documentation files resolve correctly - [ ] No type annotation warnings are produced during documentation generation ## Subtasks - [ ] Resolve MkDocs 2.0 compatibility issue (switch to ProperDocs or address warning) - [ ] Add missing documentation pages to the nav configuration in `mkdocs.yml` - [ ] Fix broken link in `api/a2a.md` referencing CHANGELOG.md - [ ] Add missing type annotations in `vocabularies.py` and `_resolve_actor.py` - [ ] Tests: Verify all documentation builds cleanly with `nox -e serve_docs` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly (`fix(docs): resolve mkdocs serve_docs build issues`), followed by a blank line, then additional lines providing implementation details. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly (`fix/m3-docs-build-issues`). - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - Running `nox -e serve_docs` produces clean output with no warnings related to the items above.
brent.edwards added this to the v3.2.0 milestone 2026-04-03 19:25:25 +00:00
Owner

Thank you for filing this issue, @brent.edwards. I've reviewed it and it is well-formed with complete metadata, subtasks, and acceptance criteria.

Triage assessment:

  • Priority: Low — documentation build warnings do not block functionality, but they should be cleaned up for a professional developer experience.
  • Milestone: v3.2.0 — appropriate since the documentation infrastructure is a cross-cutting concern.
  • Type: Documentation — correctly classified.
  • Effort: Points/2 — reasonable estimate for the scope of work (nav config updates, link fix, type annotation additions, MkDocs 2.0 compatibility).
  • Parent Epic: This issue should be linked to a documentation epic. The closest match appears to be the general documentation infrastructure.

Observations on the four sub-problems:

  1. MkDocs 2.0 compatibility: This is a known upstream issue with Material for MkDocs. The recommended path is to evaluate ProperDocs or pin the MkDocs version to avoid the warning. This should be investigated carefully since switching documentation frameworks mid-project has risk.

  2. Missing nav entries: 13 pages are orphaned from the navigation. These were likely added by recent agent-driven documentation PRs without corresponding mkdocs.yml updates. Straightforward to fix.

  3. Broken CHANGELOG.md link: The relative path ../../CHANGELOG.md in api/a2a.md is incorrect. The CHANGELOG may not exist yet or the path needs adjustment.

  4. Griffe type annotation warnings: These are in vocabularies.py and _resolve_actor.py. Adding the missing type annotations aligns with the project's strict typing requirement (CONTRIBUTING.md: "All code must be statically typed").

Next step: This issue is verified and ready for implementation.


Automated by CleverAgents Bot
Supervisor: Human Liaison | Agent: ca-human-liaison

Thank you for filing this issue, @brent.edwards. I've reviewed it and it is well-formed with complete metadata, subtasks, and acceptance criteria. **Triage assessment:** - **Priority**: Low — documentation build warnings do not block functionality, but they should be cleaned up for a professional developer experience. - **Milestone**: v3.2.0 — appropriate since the documentation infrastructure is a cross-cutting concern. - **Type**: Documentation — correctly classified. - **Effort**: Points/2 — reasonable estimate for the scope of work (nav config updates, link fix, type annotation additions, MkDocs 2.0 compatibility). - **Parent Epic**: This issue should be linked to a documentation epic. The closest match appears to be the general documentation infrastructure. **Observations on the four sub-problems:** 1. **MkDocs 2.0 compatibility**: This is a known upstream issue with Material for MkDocs. The recommended path is to evaluate ProperDocs or pin the MkDocs version to avoid the warning. This should be investigated carefully since switching documentation frameworks mid-project has risk. 2. **Missing nav entries**: 13 pages are orphaned from the navigation. These were likely added by recent agent-driven documentation PRs without corresponding `mkdocs.yml` updates. Straightforward to fix. 3. **Broken CHANGELOG.md link**: The relative path `../../CHANGELOG.md` in `api/a2a.md` is incorrect. The CHANGELOG may not exist yet or the path needs adjustment. 4. **Griffe type annotation warnings**: These are in `vocabularies.py` and `_resolve_actor.py`. Adding the missing type annotations aligns with the project's strict typing requirement (CONTRIBUTING.md: "All code must be statically typed"). **Next step**: This issue is verified and ready for implementation. --- **Automated by CleverAgents Bot** Supervisor: Human Liaison | Agent: ca-human-liaison
Owner

Issue triaged by project owner:

  • State: Verified
  • MoSCoW: Could Have

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified - **MoSCoW**: Could Have --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
Owner

Label compliance fix applied:

  • Removed conflicting State/Unverified label (org-level ID 846) — issue had both State/Unverified and State/Verified simultaneously, which is contradictory. Kept State/Verified as the more advanced state.
  • Removed duplicate Priority/Low (repo-level ID 1332) — kept org-level Priority/Low (ID 861) as canonical.
  • Reason: Per CONTRIBUTING.md, each issue must have exactly one State/* label.

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

Label compliance fix applied: - Removed conflicting `State/Unverified` label (org-level ID 846) — issue had both `State/Unverified` and `State/Verified` simultaneously, which is contradictory. Kept `State/Verified` as the more advanced state. - Removed duplicate `Priority/Low` (repo-level ID 1332) — kept org-level `Priority/Low` (ID 861) as canonical. - Reason: Per CONTRIBUTING.md, each issue must have exactly one `State/*` label. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer
freemo removed this from the v3.2.0 milestone 2026-04-06 22:29:43 +00:00
Owner

This issue has been moved to the backlog as part of an aggressive grooming of the v3.2.0 milestone. It has been deemed non-critical for the minimal viability of the milestone and will be addressed in a future release.

This issue has been moved to the backlog as part of an aggressive grooming of the v3.2.0 milestone. It has been deemed non-critical for the minimal viability of the milestone and will be addressed in a future release.
Sign in to join this conversation.
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
cleveragents/cleveragents-core#2606
No description provided.