[Aman-Mittal]

Automates the steps from #64: building the docs with ./gradlew asciidoctor, copying them with fineract-site docs, and updating .htaccess. It follows the same pattern as the API spec sync in fineract-backoffice-ui.

fineract-site docs (scripts/generate_docs.py) is unchanged. Everything new lives in .github/scripts.

What it does

.github/workflows/docs-sync.yml runs every Monday, or by hand with ref, dry_run and force inputs, and opens a PR against asf-site:

Target	When	Change
develop	develop has moved since the commit recorded in the last update /docs/*-SNAPSHOT commit	Refreshes docs/X.Y.Z-SNAPSHOT/ in place. If the backend version has rolled after a release, it removes the previous snapshot folder (so Git records a rename, as in 3c4e0c1) and points /docs/develop and the commented /docs/rc candidate at the new version.
Newest X.Y.Z tag	No docs/X.Y.Z/ yet	Adds it and points /docs/stable (and so /docs/current) at it.

When there's no new release, only the snapshot index.html changes: no rename and no .htaccess edit. A rebuild where only the "Built on" or "Last updated" stamps change opens no PR. Each target uses a fixed branch (bot/docs-develop, bot/docs-X.Y.Z), so re-runs update the open PR instead of adding new ones. Commits are signed by GitHub (sign-commits), so verify-commits.yml passes.

Layout

The workflow only calls the scripts below, so a run can be reproduced locally (README, "Automated docs sync").

• .github/scripts/docs-sync.sh: plan and build. build does the following in order:
  • checks that dot (Graphviz), vl2vg and vg2svg are present, and stops if not
  • clones the backend and deletes fineract-doc/build, so no diagram rendered while a tool was missing gets reused (see Fix broken diagrams in /docs/1.16.0 and /docs/1.17.0-SNAPSHOT; fail the build on them #66)
  • runs ./gradlew asciidoctor
  • runs fineract-site docs --version V
  • runs docs_aliases.py
  • runs the same site-tool build and checks as site-pr-check.yml, including the diagram check from Fix broken diagrams in /docs/1.16.0 and /docs/1.17.0-SNAPSHOT; fail the build on them #66
• .github/scripts/docs_aliases.py: the .htaccess and snapshot-folder changes that were done by hand. It stages them and appends a note for each to DOCS-LOG-MESSAGE. It can also be run by hand after fineract-site docs.
• .github/scripts/docs-sync-pr.sh: turns DOCS-LOG-MESSAGE into the commit message, PR title, branch and body, so no ${{ }} is interpolated into shell.
• .github/scripts/test_docs_aliases.py: unit tests for the alias logic, plus end-to-end runs against a scratch Git repo covering no release, a snapshot roll, a new release, and running before fineract-site docs. site-tool test now also runs the tests in .github/scripts.
• .github/docs-sync/package-lock.json: pins vega-cli and vega-lite. Graphviz comes from apt, since the runner image doesn't include it.

Security

• zizmor --persona=pedantic reports no findings. The one ignore is superfluous-actions on peter-evans/create-pull-request, because gh pr create can't make signed commits.
• actionlint and shellcheck are clean.
• Actions are pinned to commit SHAs, with persist-credentials: false and permissions: {} at the top level.
• Only the PR job can write. It has no cache, and its npm install runs with --ignore-scripts.
• It uses github.token only. PRs opened with that token don't trigger other workflows, so the job itself runs the same site-tool build and checks as site-pr-check.yml.

Verified locally

On this commit, in a fresh clone:

• build develop develop from a simulated pre-roll state (/docs/develop pointing at 1.16.0-SNAPSHOT), built from develop at apache/fineract@01bb02b:
  • Git records docs/1.16.0-SNAPSHOT/index.html -> docs/1.17.0-SNAPSHOT/index.html as a rename.
  • /docs/develop and the /docs/rc candidate move to 1.17.0.
  • The commit message gets the three notes.
  • The new page has no broken diagrams, and the internal link, diagram and Whimsy checks pass.
• site-tool test: the Ruby suite (23 runs) and 21 Python tests (13 from Fix broken diagrams in /docs/1.16.0 and /docs/1.17.0-SNAPSHOT; fail the build on them #66, 8 here) pass.
• zizmor (all personas), actionlint and shellcheck are clean.

From the earlier round, unchanged since: plan plans nothing while develop is still at the commit the snapshot docs came from, plans a release build when given 1.16.0, and rejects a malformed ref. A rebuild of an unchanged commit gives changed=false, so no PR. docs-sync-pr.sh produces the expected commit message, branch and body.

Note

The first run will change the widths of the Vega-Lite diagrams compared with the hand-built pages. Without the native canvas module (skipped by --ignore-scripts), Vega estimates text widths instead of measuring real fonts. Output is byte-identical from run to run, so this is a one-time diff.

[Aman-Mittal]

Closing this needs testing