You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@fineract.apache.org by me...@apache.org on 2026/07/14 20:35:25 UTC
(fineract-site) branch asf-site updated (38aacbc -> c20b227)
This is an automated email from the ASF dual-hosted git repository.
meonkeys pushed a change to branch asf-site
in repository https://gitbox.apache.org/repos/asf/fineract-site.git
from 38aacbc bot chore: generate site [skip-generate]
new bb2276d automate /docs/VERSION updates
new c266d89 help doc updater with commit log message
new c20b227 clean up docs written by Claude
The 3 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
.github/workflows/generate-static-site.yml | 1 +
.gitignore | 3 +
README.md | 41 ++++++++
scripts/generate_docs.py | 163 +++++++++++++++++++++++++++++
scripts/site-tool.sh | 10 +-
5 files changed, 217 insertions(+), 1 deletion(-)
create mode 100644 scripts/generate_docs.py
(fineract-site) 03/03: clean up docs written by Claude
Posted by me...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
meonkeys pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/fineract-site.git
commit c20b227ee769e968fd74bc868335a020627dabce
Author: Adam Monsen <ha...@gmail.com>
AuthorDate: Tue Jul 14 13:32:34 2026 -0700
clean up docs written by Claude
---
README.md | 11 ++++++-----
1 file changed, 6 insertions(+), 5 deletions(-)
diff --git a/README.md b/README.md
index 9c1f920..ac77e3c 100644
--- a/README.md
+++ b/README.md
@@ -66,7 +66,7 @@ backend. To refresh it:
./gradlew asciidoctor
```
- Make sure the clone's working tree is clean (`git status`) — the commit hash
+ Make sure the clone's working tree is clean (`git status`) -- the commit hash
is recorded so the copied doc can be traced back to the exact source commit.
2. Run the `docs` command in the site tool image, mounting both repos:
@@ -84,11 +84,12 @@ backend. To refresh it:
This copies `fineract-doc/build/docs/html/en/index.html` from the backend clone
into `docs/VERSION/index.html`, then rewrites the Google Fonts and Font Awesome
-CDN links to point at the site's local `css/` stylesheets. Versions ending in
-`-SNAPSHOT` are overwritten; released versions are not.
+CDN links to point at the site's local `css/` stylesheets (per Apache project
+website requirements). Versions ending in `-SNAPSHOT` are overwritten; released
+versions are not.
-It also writes and `git add`s a `DOCS-LOG-MESSAGE` file (git-ignored) with a suggested commit message referencing the source commit.
-Use it to commit the update:
+It also prepares a suggested commit message referencing the source commit.
+Use it like so:
```bash
git commit -F DOCS-LOG-MESSAGE
(fineract-site) 02/03: help doc updater with commit log message
Posted by me...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
meonkeys pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/fineract-site.git
commit c266d890994859969468f8e59b755a3a022fb0a0
Author: Adam Monsen <ha...@gmail.com>
AuthorDate: Tue Jul 14 13:25:30 2026 -0700
help doc updater with commit log message
Coded by Claude (model=Sonnet 5, effort=High).
I made edits (e.g. add_to_git), reviewed, and tested this.
---
.github/workflows/generate-static-site.yml | 1 +
.gitignore | 3 +++
README.md | 7 +++++++
scripts/generate_docs.py | 28 +++++++++++++++++++++++-----
4 files changed, 34 insertions(+), 5 deletions(-)
diff --git a/.github/workflows/generate-static-site.yml b/.github/workflows/generate-static-site.yml
index 00f7aa5..6da81dd 100644
--- a/.github/workflows/generate-static-site.yml
+++ b/.github/workflows/generate-static-site.yml
@@ -50,6 +50,7 @@ jobs:
--exclude 'README.md' \
--exclude 'CONTRIBUTING.md' \
--exclude 'LICENSE.txt' \
+ --exclude 'DOCS-LOG-MESSAGE' \
.build/site/ ./
- name: Commit and push generated output
diff --git a/.gitignore b/.gitignore
index 8c58332..cd9ceee 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,3 +9,6 @@ site-src/resources/
# Hugo lock file
site-src/.hugo_build.lock
+
+# Generated commit message for docs/VERSION updates (scripts/generate_docs.py)
+/DOCS-LOG-MESSAGE
diff --git a/README.md b/README.md
index 45894e4..9c1f920 100644
--- a/README.md
+++ b/README.md
@@ -87,6 +87,13 @@ into `docs/VERSION/index.html`, then rewrites the Google Fonts and Font Awesome
CDN links to point at the site's local `css/` stylesheets. Versions ending in
`-SNAPSHOT` are overwritten; released versions are not.
+It also writes and `git add`s a `DOCS-LOG-MESSAGE` file (git-ignored) with a suggested commit message referencing the source commit.
+Use it to commit the update:
+
+```bash
+git commit -F DOCS-LOG-MESSAGE
+```
+
## Verifying ASF project website compliance
Apache Whimsy periodically checks that the public homepage follows ASF conventions.
diff --git a/scripts/generate_docs.py b/scripts/generate_docs.py
index 3ffb3f9..bcd878b 100644
--- a/scripts/generate_docs.py
+++ b/scripts/generate_docs.py
@@ -34,6 +34,7 @@ from pathlib import Path
REPO_ROOT = Path(__file__).resolve().parent.parent
DEFAULT_BACKEND_DIR = "/fineract"
DOC_HTML_RELATIVE_PATH = Path("fineract-doc/build/docs/html/en/index.html")
+COMMIT_MESSAGE_PATH = REPO_ROOT / "DOCS-LOG-MESSAGE"
# Same substitution made by hand in commits like e70425660b42fc705760006141078e870df0a566.
GOOGLE_FONTS_LINK = (
@@ -92,6 +93,22 @@ def get_commit_hash(backend_dir):
return run_git(backend_dir, "rev-parse", "HEAD").stdout.strip()
+def add_to_git(repo_dir, file):
+ return run_git(repo_dir, "add", file).stdout.strip()
+
+
+def write_commit_message(version, commit_hash):
+ message = (
+ f"update /docs/{version}\n"
+ "\n"
+ "docs built with `./gradlew asciidoctor` from "
+ f"https://github.com/apache/fineract/commit/{commit_hash}\n"
+ "\n"
+ "added here using the `fineract-site docs`"
+ )
+ COMMIT_MESSAGE_PATH.write_text(message, encoding="utf-8")
+
+
def localize_stylesheets(html_path):
text = html_path.read_text(encoding="utf-8")
text = text.replace(GOOGLE_FONTS_LINK, LOCAL_STYLESHEET_LINK)
@@ -119,11 +136,6 @@ def main():
commit_hash = get_commit_hash(backend_dir)
print(f"Backend commit: {commit_hash}")
- github_output = os.environ.get("GITHUB_OUTPUT")
- if github_output:
- with open(github_output, "a", encoding="utf-8") as f:
- f.write(f"fineract_commit={commit_hash}\n")
-
dest_dir = REPO_ROOT / "docs" / args.version
dest_html = dest_dir / "index.html"
is_snapshot = args.version.endswith("-SNAPSHOT")
@@ -139,6 +151,12 @@ def main():
localize_stylesheets(dest_html)
print(f"Wrote {dest_html}")
+ add_to_git(dest_dir, dest_html)
+ print(f"Added {dest_html} to Git index")
+
+ write_commit_message(args.version, commit_hash)
+ print(f"Wrote {COMMIT_MESSAGE_PATH}")
+ print(f"Run: git commit -F {COMMIT_MESSAGE_PATH.name}")
if __name__ == "__main__":
(fineract-site) 01/03: automate /docs/VERSION updates
Posted by me...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
meonkeys pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/fineract-site.git
commit bb2276d2565e33293b6414d3bc9424c3c151d5d5
Author: Adam Monsen <ha...@gmail.com>
AuthorDate: Tue Jul 14 13:04:31 2026 -0700
automate /docs/VERSION updates
Coded by Claude (model=Sonnet 5, effort=High).
I reviewed and tested this.
---
README.md | 33 +++++++++++
scripts/generate_docs.py | 145 +++++++++++++++++++++++++++++++++++++++++++++++
scripts/site-tool.sh | 10 +++-
3 files changed, 187 insertions(+), 1 deletion(-)
diff --git a/README.md b/README.md
index 58b811a..45894e4 100644
--- a/README.md
+++ b/README.md
@@ -54,6 +54,39 @@ docker run --rm -v "${PWD}:/src" -w /src/site-src fineract-site build
docker run --rm -it -p 1313:1313 -v "${PWD}:/src" -w /src/site-src fineract-site serve
```
+## Updating `/docs/VERSION` from a Fineract backend clone
+
+`docs/VERSION` (e.g. `docs/1.16.0-SNAPSHOT`) holds the rendered Fineract API
+documentation built from the [apache/fineract](https://github.com/apache/fineract)
+backend. To refresh it:
+
+1. In your clone of `apache/fineract`, generate the docs:
+
+ ```bash
+ ./gradlew asciidoctor
+ ```
+
+ Make sure the clone's working tree is clean (`git status`) — the commit hash
+ is recorded so the copied doc can be traced back to the exact source commit.
+
+2. Run the `docs` command in the site tool image, mounting both repos:
+
+ ```bash
+ docker run --rm -u "$(id -u):$(id -g)" \
+ -v "$PWD:/src" \
+ -v /path/to/fineract:/fineract:ro \
+ -w /src \
+ fineract-site docs --version 1.16.0-SNAPSHOT
+ ```
+
+ The version can also be set via `FINERACT_DOC_VERSION`, and the backend
+ mount path via `FINERACT_REPO_DIR` (default `/fineract`).
+
+This copies `fineract-doc/build/docs/html/en/index.html` from the backend clone
+into `docs/VERSION/index.html`, then rewrites the Google Fonts and Font Awesome
+CDN links to point at the site's local `css/` stylesheets. Versions ending in
+`-SNAPSHOT` are overwritten; released versions are not.
+
## Verifying ASF project website compliance
Apache Whimsy periodically checks that the public homepage follows ASF conventions.
diff --git a/scripts/generate_docs.py b/scripts/generate_docs.py
new file mode 100644
index 0000000..3ffb3f9
--- /dev/null
+++ b/scripts/generate_docs.py
@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+"""Copy generated Fineract API docs from a backend clone into docs/VERSION.
+
+Assumes the backend (apache/fineract) has already been built with
+`./gradlew asciidoctor` and is available at --backend-dir (or
+$FINERACT_REPO_DIR), e.g. mounted as a Docker volume.
+"""
+
+import argparse
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+DEFAULT_BACKEND_DIR = "/fineract"
+DOC_HTML_RELATIVE_PATH = Path("fineract-doc/build/docs/html/en/index.html")
+
+# Same substitution made by hand in commits like e70425660b42fc705760006141078e870df0a566.
+GOOGLE_FONTS_LINK = (
+ '<link rel="stylesheet" href="https://fonts.googleapis.com/css?family='
+ "Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,"
+ '400italic,700,700italic%7CDroid+Sans+Mono:400,700">'
+)
+LOCAL_STYLESHEET_LINK = '<link rel="stylesheet" href="../../css/stylesheet.css">'
+FONT_AWESOME_CDN_LINK = (
+ '<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/'
+ 'font-awesome/4.7.0/css/font-awesome.min.css">'
+)
+FONT_AWESOME_LOCAL_LINK = '<link rel="stylesheet" href="../../css/font-awesome.min.css">'
+
+
+def parse_args():
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument(
+ "--version",
+ default=os.environ.get("FINERACT_DOC_VERSION"),
+ help="Doc version folder to write, e.g. 1.16.0-SNAPSHOT "
+ "(default: $FINERACT_DOC_VERSION)",
+ )
+ parser.add_argument(
+ "--backend-dir",
+ default=os.environ.get("FINERACT_REPO_DIR", DEFAULT_BACKEND_DIR),
+ help="Path to the apache/fineract clone "
+ f"(default: $FINERACT_REPO_DIR or {DEFAULT_BACKEND_DIR})",
+ )
+ args = parser.parse_args()
+ if not args.version:
+ parser.error("a version is required: pass --version or set FINERACT_DOC_VERSION")
+ return args
+
+
+def run_git(backend_dir, *git_args):
+ return subprocess.run(
+ ["git", "-C", str(backend_dir), *git_args],
+ check=True,
+ capture_output=True,
+ text=True,
+ )
+
+
+def require_clean_git_status(backend_dir):
+ result = run_git(backend_dir, "status", "--porcelain")
+ if result.stdout.strip():
+ sys.exit(
+ f"Backend clone at {backend_dir} is not clean (git status --porcelain "
+ "reported changes). Commit or stash them so the copied doc can be "
+ f"traced back to an exact commit:\n{result.stdout}"
+ )
+
+
+def get_commit_hash(backend_dir):
+ return run_git(backend_dir, "rev-parse", "HEAD").stdout.strip()
+
+
+def localize_stylesheets(html_path):
+ text = html_path.read_text(encoding="utf-8")
+ text = text.replace(GOOGLE_FONTS_LINK, LOCAL_STYLESHEET_LINK)
+ text = text.replace(FONT_AWESOME_CDN_LINK, FONT_AWESOME_LOCAL_LINK)
+ if not text.endswith("\n"):
+ text += "\n"
+ html_path.write_text(text, encoding="utf-8")
+
+
+def main():
+ args = parse_args()
+ backend_dir = Path(args.backend_dir)
+
+ if not backend_dir.is_dir():
+ sys.exit(f"Backend directory not found: {backend_dir}")
+
+ source_html = backend_dir / DOC_HTML_RELATIVE_PATH
+ if not source_html.is_file():
+ sys.exit(
+ f"{source_html} not found. Generate it first by running "
+ "'./gradlew asciidoctor' in the backend clone."
+ )
+
+ require_clean_git_status(backend_dir)
+ commit_hash = get_commit_hash(backend_dir)
+ print(f"Backend commit: {commit_hash}")
+
+ github_output = os.environ.get("GITHUB_OUTPUT")
+ if github_output:
+ with open(github_output, "a", encoding="utf-8") as f:
+ f.write(f"fineract_commit={commit_hash}\n")
+
+ dest_dir = REPO_ROOT / "docs" / args.version
+ dest_html = dest_dir / "index.html"
+ is_snapshot = args.version.endswith("-SNAPSHOT")
+
+ if dest_html.exists() and not is_snapshot:
+ sys.exit(
+ f"{dest_html} already exists and {args.version} is not a -SNAPSHOT "
+ "version. Refusing to overwrite a released doc."
+ )
+
+ dest_dir.mkdir(parents=True, exist_ok=True)
+ shutil.copy2(source_html, dest_html)
+ localize_stylesheets(dest_html)
+
+ print(f"Wrote {dest_html}")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/scripts/site-tool.sh b/scripts/site-tool.sh
index 139e99d..f821c33 100644
--- a/scripts/site-tool.sh
+++ b/scripts/site-tool.sh
@@ -3,11 +3,12 @@ set -euo pipefail
usage() {
cat <<'EOF'
-Usage: site-tool <build|check|serve|shell> [args...]
+Usage: site-tool <build|check|docs|serve|shell> [args...]
Commands:
build Build site into /src/.build/site and run checks
check Run internal link check against /src/.build/site
+ docs Copy generated Fineract API docs into /src/docs/VERSION
test Run unit tests for whimsy checks
serve Run hugo server on port 1313
shell Open an interactive shell
@@ -52,6 +53,10 @@ run_tests() {
ruby "${REPO_ROOT}/scripts/test_run_whimsy_checks.rb"
}
+generate_docs() {
+ python3 "${REPO_ROOT}/scripts/generate_docs.py" "$@"
+}
+
serve_site() {
cd "${SITE_SRC_DIR}"
hugo server --bind 0.0.0.0 --baseURL "http://localhost:1313" --buildDrafts --disableFastRender "$@"
@@ -75,6 +80,9 @@ main() {
check)
run_checks
;;
+ docs)
+ generate_docs "$@"
+ ;;
test)
run_tests
;;