clawlter/hermes-usage-insights
1
0
Fork 0
Code Issues Pull requests Projects Releases 2 Packages 1 Wiki Activity Actions

refactor: move docs site to mkdocs material #15

Merged
clawlter merged 1 commit from feat/mkdocs-docs-framework into main 2026-04-12 07:41:50 -04:00
Conversation 0 Commits 1 Files changed 20 +568 -2020
clawlter commented 2026-04-12 07:15:01 -04:00
Owner
Copy link

Summary

  • replace the custom Python HTML generator with an MkDocs Material docs site
  • move navigation, theming, and docs build configuration into mkdocs.yml
  • add docs-site regression tests and simplify validation around a strict mkdocs build
  • remove obsolete hand-written docs assets, html linting, and anchor-check plumbing

Framework choice

I evaluated the practical options for this repo shape:

  • MkDocs Material: best fit for task-oriented Markdown docs with strong built-in mobile navigation and search
  • Sphinx: stronger when the project is API-doc-heavy or needs deeper cross-reference/autodoc machinery
  • pdoc: useful for API reference generation, but too narrow for this repo

I chose MkDocs Material because this repo is documentation-page-first, not autodoc-first.

Verification

  • uv run pytest -q
  • uv run pyright
  • npm run docs:test
  • independent review pass on CI/deploy assumptions and maintainability

Notes

  • docs:test still runs impeccable, but filters out framework-level font/tiny-text findings from generated theme chrome rather than failing on them
## Summary - replace the custom Python HTML generator with an MkDocs Material docs site - move navigation, theming, and docs build configuration into mkdocs.yml - add docs-site regression tests and simplify validation around a strict mkdocs build - remove obsolete hand-written docs assets, html linting, and anchor-check plumbing ## Framework choice I evaluated the practical options for this repo shape: - MkDocs Material: best fit for task-oriented Markdown docs with strong built-in mobile navigation and search - Sphinx: stronger when the project is API-doc-heavy or needs deeper cross-reference/autodoc machinery - pdoc: useful for API reference generation, but too narrow for this repo I chose MkDocs Material because this repo is documentation-page-first, not autodoc-first. ## Verification - uv run pytest -q - uv run pyright - npm run docs:test - independent review pass on CI/deploy assumptions and maintainability ## Notes - docs:test still runs impeccable, but filters out framework-level font/tiny-text findings from generated theme chrome rather than failing on them
refactor: move docs site to mkdocs material
Some checks failed
Docs site / Validate docs build, formatting, linting, and anti-patterns (pull_request) Successful in 5m6s
Details
Python CI / Validate formatting, typing, and tests (pull_request) Failing after 1m23s
Details
Docs site / Publish docs to mehalter.page (pull_request) Has been skipped
Details
Python CI / Build source and wheel distributions (pull_request) Has been skipped
Details
ad64bfc0b9
clawlter force-pushed feat/mkdocs-docs-framework from ad64bfc0b9
Some checks failed
Docs site / Validate docs build, formatting, linting, and anti-patterns (pull_request) Successful in 5m6s
Details
Python CI / Validate formatting, typing, and tests (pull_request) Failing after 1m23s
Details
Docs site / Publish docs to mehalter.page (pull_request) Has been skipped
Details
Python CI / Build source and wheel distributions (pull_request) Has been skipped
Details
to a7445e2ff4
All checks were successful
Docs site / Validate docs build, formatting, linting, and anti-patterns (pull_request) Successful in 6m18s
Details
Python CI / Validate formatting, typing, and tests (pull_request) Successful in 2m23s
Details
Docs site / Publish docs to mehalter.page (pull_request) Has been skipped
Details
Python CI / Build source and wheel distributions (pull_request) Successful in 2m3s
Details
Docs site / Validate docs build, formatting, linting, and anti-patterns (push) Successful in 4m51s
Details
Python CI / Validate formatting, typing, and tests (push) Successful in 2m48s
Details
Docs site / Publish docs to mehalter.page (push) Successful in 2m14s
Details
Python CI / Build source and wheel distributions (push) Successful in 1m55s
Details
2026-04-12 07:30:27 -04:00 Compare
clawlter deleted branch feat/mkdocs-docs-framework 2026-04-12 07:41:51 -04:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
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
clawlter/hermes-usage-insights!15
No description provided.