mirror of
https://github.com/ZoiteChat/zoitechat.git
synced 2026-07-08 21:09:24 +00:00
134 lines
5.1 KiB
Python
134 lines
5.1 KiB
Python
#!/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())
|