Repository navigation
Fix broken diagrams in /docs/1.16.0 and /docs/1.17.0-SNAPSHOT; fail the build on them - #66
Merged
Merged
Conversation
Both pages were built without Graphviz installed. `./gradlew asciidoctor` still succeeded, but PlantUML drew a "Cannot find Graphviz" error image in place of 8 diagrams per page (7 SVG, 1 PNG), among them the release process diagram at /docs/stable/#_release_process. Rebuilt from the same backend commits as before: - 1.16.0 from apache/fineract@6da8a98 (the 1.16.0 tag), with `fineract-site docs --replace-release` - 1.17.0-SNAPSHOT from apache/fineract@f1723d7 Only those 8 diagrams and the build timestamps change.
Add scripts/check_doc_diagrams.py, run by `fineract-site build` and so by site-pr-check.yml. It decodes every diagram embedded in docs/*/index.html and fails on PlantUML error images: SVGs by their error text, and PlantUML PNGs, whose metadata is the same either way, by the #33FF02 green PlantUML draws that text in. `fineract-site docs` now refuses to copy a page with such diagrams, and gains --replace-release to republish a released version from its tag. The check also found a broken PNG in docs/1.13.0, published that way in October 2025. 1.13.0 is EOL, so it is recorded in KNOWN_BROKEN with its exact count rather than rebuilt; any other broken diagram still fails. Tests (scripts/test_check_doc_diagrams.py, run by `fineract-site test`) use the broken and rebuilt batch-jobs PNGs from docs/1.16.0 as fixtures.
Aman-Mittal
added a commit
that referenced
this pull request
Oct 25, 2026
Without Graphviz, `./gradlew asciidoctor` still succeeds but PlantUML publishes a "Cannot find Graphviz" image in place of each diagram, as fixed for 1.16.0 and 1.17.0-SNAPSHOT in #66. The runner image does not ship it, so the workflow installs it, and docs-sync.sh stops before building when `dot` is missing. docs-sync.sh also deletes fineract-doc/build before building: a reused backend clone can hold diagrams rendered while a tool was missing, which asciidoctor-diagram would keep and Gradle cannot tell are stale.
Aman-Mittal
added a commit
that referenced
this pull request
Oct 25, 2026
Add .github/workflows/docs-sync.yml, which rebuilds the Fineract docs weekly (or on demand) and opens a PR against asf-site: - develop: refreshes docs/X.Y.Z-SNAPSHOT behind /docs/develop, skipped when develop has not moved or only the build timestamps changed. - the newest X.Y.Z release tag without docs/X.Y.Z/: adds it and points /docs/stable at it. The workflow only calls scripts in .github/scripts, so a run can be reproduced and verified locally: - docs-sync.sh: plan, and build (backend clone, asciidoctor, then `fineract-site docs` unchanged, then docs_aliases.py, then the same site build and checks as site-pr-check.yml). It stops before building when Graphviz or the Vega CLI tools are missing, and deletes fineract-doc/build first so no stale diagram is reused (see #66). - docs_aliases.py: the .htaccess changes done by hand so far. With no new release it changes nothing; when the snapshot version rolls it removes the previous snapshot folder so Git records a rename, as in 3c4e0c1. - docs-sync-pr.sh: commit message, PR title, branch and body. The Vega CLI tools are pinned in .github/docs-sync/package-lock.json; Graphviz comes from apt. `fineract-site test` also runs the tests in .github/scripts.
Contributor
|
probably better to have the checks for dependencies / correct rendering in the apache/fineract repo? I guess we only deploy docs here using this repo, but it makes more sense to me that the same thing actually generating the docs (asciidoctor via gradle in the apache/fineract repo) would also have those checks. And I'd lean quicker / easier to maintain rather than exhaustive... this seems like too much code. Could be just a couple simpler checks. |
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
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 broken diagrams published in #64, for example at https://fineract.apache.org/docs/stable/#_release_process, where the release process diagram shows "Cannot find Graphviz".
Cause
The pages in #64 were built on a machine without Graphviz (
dot)../gradlew asciidoctorstill reports success, but PlantUML draws an error image in place of every diagram that needs Graphviz. Each page had 8 of them: 7 SVGs (the command-processing architecture diagrams,m_wc_loan, and the release process) and 1 PNG (the batch-jobs fault-tolerance diagram).Changes
rebuild /docs/1.16.0 and /docs/1.17.0-SNAPSHOT with Graphviz1.16.0tag (apache/fineract@6da8a98) anddevelopat apache/fineract@f1723d7.fail the site build on diagrams rendered as PlantUML errorsscripts/check_doc_diagrams.pydecodes every diagram embedded indocs/*/index.htmland fails on PlantUML error images. It finds SVGs by their error text. PlantUML PNGs carry the same metadata whether or not they rendered, so it finds those by the#33FF02green that PlantUML draws its error text in. Only PNGs that PlantUML tagged are decoded, so the check takes well under a second.fineract-site build, sosite-pr-check.ymlruns it on every PR.fineract-site docsnow refuses to copy a page with broken diagrams.fineract-site docsgains--replace-releasefor republishing a released version from its tag, which is how 1.16.0 was replaced here. Without the flag, overwriting a release is still refused.Known exception: 1.13.0
The new check also found the same broken batch-jobs PNG in
docs/1.13.0, published that way in October 2025. Since 1.13.0 is EOL, it's recorded inKNOWN_BROKENwith its exact count (1) rather than rebuilt. A different count fails, and so does a fix that leaves the entry in place. If we'd rather fix it, the diagram's PlantUML source is embedded in the PNG, so that one image could be re-rendered.Testing
asf-site, the check fails with 16 broken diagrams (8 each in 1.16.0 and 1.17.0-SNAPSHOT). With this branch it passes.fineract-site build: the internal link check, the docs diagram check and the Whimsy checks pass.fineract-site test: the existing Ruby suite and 13 new Python tests pass. The tests use the broken and rebuilt batch-jobs PNGs fromdocs/1.16.0as fixtures, and cover every PNG row-filter type, with and without an alpha channel.Follow-up
#65 (draft, the docs-sync workflow) will be rebased on this. It also needs to install Graphviz and to fail early when
dotis missing.