docs: regenerate architecture diagrams on every mkdocs build (#89)#96
Merged
Conversation
Add an MkDocs on_pre_build hook (tools/mkdocs_hooks.py) wired into mkdocs.yml so that the architecture diagrams are actually regenerated on every documentation build, matching what docs/architecture.md claims. The hook invokes tools/generate_diagrams.py and falls back to small placeholder SVGs when pyreverse or Graphviz is unavailable, so 'mkdocs build --strict' no longer fails on missing image links in environments without the diagram toolchain. - Update docs/architecture.md to describe the real workflow. - Ignore docs/architecture/ and site/ in .gitignore so generated artifacts are not committed. - Add tests/test_mkdocs_hooks.py covering the success path, the toolchain-missing fallback, the generator-failure fallback, and the placeholder writer's no-overwrite behaviour.
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
1 participant
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 #89.
Issue validity
Valid. Verified locally:
mkdocs build --strictfailed with two warnings about missingarchitecture/classes.svgandarchitecture/packages.svg. The pagedocs/architecture.mdclaimed the diagrams were "regenerated from source on every docs build," butmkdocs.ymldid not actually invoketools/generate_diagrams.py. CI ran the generator as a separate step (.github/workflows/docs.yml), but local strict builds were broken.Fix
tools/mkdocs_hooks.py— new MkDocson_pre_buildhook that runstools/generate_diagrams.pybefore MkDocs validates inter-page links. Ifpyreverseor Graphvizdotis unavailable, it writes minimal placeholder SVGs somkdocs build --strictstill succeeds.mkdocs.yml— register the hook via thehooks:setting. This makes the documentation now genuinely regenerate diagrams on every build, matching the page's claim.docs/architecture.md— rewrite to describe the real workflow accurately (hook + generator script + Graphviz prerequisite + manual regeneration command)..gitignore— ignoredocs/architecture/(generated SVGs) andsite/(mkdocs output).tests/test_mkdocs_hooks.py— 7 new tests covering: toolchain-missing fallback, generator-failure fallback, successful generation path, placeholder writer preserving existing files,_has_prerequisitesfalse branches for missingdotand missingpyreverse, and_run_generatorsubprocess-failure path.Validation
pytest tests/ --cov=haclient --cov-report=term-missing --cov-fail-under=95— 326 passed, coverage 97.18%ruff check src tests tools— cleanruff format --check src tests tools— cleanmypy src— clean (Success: no issues found in 38 source files)mkdocs build --strict— succeeds locally; hook runs the generator and produces real SVGs