offline docs by default.

data/meson.build

@@ -6,4 +6,29 @@ if get_option('gtk-frontend')
   subdir('icons')
   subdir('misc')
   subdir('man')
+
+  # Fetch and build the offline manual so Help->Contents works without
+  # connectivity. 'auto' skips with a warning when the docs cannot be
+  # fetched (e.g. network-less distro builds, which ship docs themselves);
+  # 'enabled' makes that a hard error.
+  offline_docs_opt = get_option('offline-docs')
+  if not offline_docs_opt.disabled()
+    offline_docs_args = [
+      '--repo', get_option('offline-docs-repo'),
+      '--output', join_paths(meson.current_build_dir(), 'offline-docs'),
+      '--stamp', '@OUTPUT@',
+    ]
+    if offline_docs_opt.enabled()
+      offline_docs_args += ['--strict']
+    endif
+    custom_target('offline-docs',
+      output: 'offline-docs.stamp',
+      command: [find_program('python3'), files('misc/build_offline_docs.py')] + offline_docs_args,
+      build_by_default: true,
+    )
+    meson.add_install_script(files('misc/install_offline_docs.py'),
+      join_paths(meson.current_build_dir(), 'offline-docs'),
+      offline_docs_dir,
+    )
+  endif
 endif

data/misc/build_offline_docs.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+"""Build ZoiteChat's offline HTML documentation for bundling with releases.
+
+Clones the ZoiteChat/documentation repository, preferring a tag that
+matches this source tree's version so the bundled manual matches the
+application, and builds it with Sphinx into --output. Used by the
+meson build (offline-docs option) and by the Windows CI workflow.
+
+Sphinx is installed into a throwaway virtualenv so the invoking Python
+(which the Windows build also bundles pieces of) is left untouched.
+
+Unless --strict is given, any failure prints a warning (GitHub Actions
+annotation syntax) and exits 0: builds then simply fall back to opening
+the online manual instead of failing outright.
+"""
+
+import argparse
+import pathlib
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+
+DEFAULT_REPO = "https://github.com/ZoiteChat/documentation.git"
+
+
+def project_version() -> str:
+    meson_build = pathlib.Path(__file__).resolve().parents[2] / "meson.build"
+    match = re.search(r"version\s*:\s*'([^']+)'", meson_build.read_text(encoding="utf-8"))
+    if not match:
+        raise RuntimeError(f"could not parse project version from {meson_build}")
+    return match.group(1)
+
+
+def run(argv, **kwargs) -> None:
+    print("+", " ".join(str(arg) for arg in argv), flush=True)
+    subprocess.run(argv, check=True, **kwargs)
+
+
+def clone_docs(repo: str, version: str, target: pathlib.Path) -> str:
+    # A missing tag falls through to the default branch so the docs may be
+    # newer than the app, which beats shipping none at all.
+    for ref in (f"v{version}", version, None):
+        cmd = ["git", "clone", "--depth", "1"]
+        if ref:
+            cmd += ["--branch", ref]
+        cmd += [repo, str(target)]
+        try:
+            run(cmd)
+            return ref or "default branch"
+        except subprocess.CalledProcessError:
+            shutil.rmtree(target, ignore_errors=True)
+    raise RuntimeError(f"could not clone {repo}")
+
+
+def find_source_dir(checkout: pathlib.Path) -> pathlib.Path:
+    for candidate in (checkout, checkout / "docs", checkout / "doc"):
+        if (candidate / "conf.py").is_file():
+            return candidate
+    raise RuntimeError(f"no Sphinx conf.py found in {checkout}")
+
+
+def venv_python(venv_dir: pathlib.Path) -> pathlib.Path:
+    if sys.platform == "win32":
+        return venv_dir / "Scripts" / "python.exe"
+    return venv_dir / "bin" / "python"
+
+
+def build(output: pathlib.Path, repo: str, version: str) -> None:
+    with tempfile.TemporaryDirectory(prefix="zoitechat-docs-") as tmp:
+        tmp_dir = pathlib.Path(tmp)
+        checkout = tmp_dir / "documentation"
+        html_dir = tmp_dir / "html"
+        venv_dir = tmp_dir / "venv"
+
+        ref = clone_docs(repo, version, checkout)
+        print(f"building documentation from {ref}", flush=True)
+        source_dir = find_source_dir(checkout)
+
+        run([sys.executable, "-m", "venv", str(venv_dir)])
+        python = venv_python(venv_dir)
+        requirements = source_dir / "requirements.txt"
+        if not requirements.is_file():
+            requirements = checkout / "requirements.txt"
+        if requirements.is_file():
+            run([python, "-m", "pip", "install", "--quiet", "-r", str(requirements)])
+            run([python, "-m", "pip", "install", "--quiet", "sphinx"])
+        else:
+            run([python, "-m", "pip", "install", "--quiet", "sphinx", "sphinx_rtd_theme"])
+
+        run([python, "-m", "sphinx", "-b", "html", str(source_dir), str(html_dir)])
+        if not (html_dir / "index.html").is_file():
+            raise RuntimeError("Sphinx build produced no index.html")
+
+        if output.exists():
+            shutil.rmtree(output)
+        shutil.copytree(html_dir, output,
+                        ignore=shutil.ignore_patterns(".doctrees", ".buildinfo"))
+
+    file_count = sum(1 for path in output.rglob("*") if path.is_file())
+    print(f"offline documentation staged at {output} ({file_count} files)", flush=True)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--output", required=True, type=pathlib.Path,
+                        help="directory to stage the built HTML tree into")
+    parser.add_argument("--repo", default=DEFAULT_REPO,
+                        help="documentation git repository to build from")
+    parser.add_argument("--version", default=None,
+                        help="app version used to pick a matching docs tag "
+                             "(default: parsed from meson.build)")
+    parser.add_argument("--strict", action="store_true",
+                        help="fail on error instead of emitting a warning")
+    parser.add_argument("--stamp", type=pathlib.Path, default=None,
+                        help="file to touch on completion (meson target output)")
+    args = parser.parse_args()
+
+    try:
+        build(args.output, args.repo, args.version or project_version())
+    except Exception as error:  # noqa: BLE001 - degrade to website-only help
+        if args.strict:
+            raise
+        print(f"::warning::offline documentation not bundled: {error}", flush=True)
+
+    if args.stamp:
+        args.stamp.write_text("ok\n", encoding="utf-8")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

data/misc/install_offline_docs.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+"""Meson install helper: copy the built offline docs into the install tree.
+
+Silently skips when the docs were not built (offline-docs=auto without
+network); Help->Contents then falls back to the online manual.
+"""
+
+import os
+import pathlib
+import shutil
+import sys
+
+src = pathlib.Path(sys.argv[1])
+dest_arg = pathlib.PurePath(sys.argv[2])
+
+if not (src / "index.html").is_file():
+    print("offline documentation was not built; skipping install")
+    sys.exit(0)
+
+if dest_arg.is_absolute():
+    # An absolute offline-docs-dir lands outside the prefix; honour DESTDIR
+    destdir = os.environ.get("DESTDIR", "")
+    dest = pathlib.Path(destdir + str(dest_arg)) if destdir else pathlib.Path(dest_arg)
+else:
+    dest = pathlib.Path(os.environ["MESON_INSTALL_DESTDIR_PREFIX"]) / dest_arg
+
+if dest.exists():
+    shutil.rmtree(dest)
+dest.parent.mkdir(parents=True, exist_ok=True)
+shutil.copytree(src, dest)
+print(f"Installed offline documentation to {dest}")