fr-docs 3.1.0__tar.gz → 3.3.0__tar.gz

{fr_docs-3.1.0 → fr_docs-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fr-docs
-Version: 3.1.0
+Version: 3.3.0
 Summary: Fast static documentation generator with search, versioning, and zero-config setup
 Author: Omena0
 License: # PolyForm Noncommercial License 1.0.0

{fr_docs-3.1.0 → fr_docs-3.3.0}/fr_docs/__main__.py

@@ -12,6 +12,7 @@ import sys
 
 from .build import main as build_main
 from .init import main as init_main
+from .update import main as update_main
 
 
 def main() -> None:
@@ -69,6 +70,16 @@ def main() -> None:
         help="Initialize only the configuration or download fonts.",
     )
 
+    # Update command
+    update_parser = subparsers.add_parser(
+        "update",
+        help="Update fr-docs resources (script.js, style.css, fonts) from the repo.",
+    )
+    update_parser.add_argument(
+        "--config",
+        help="Path to the configuration JSON file.",
+    )
+
     args = parser.parse_args(sys.argv[1:])
 
     if args.command == "build":
@@ -95,6 +106,13 @@ def main() -> None:
         init_main(args.dir, args.target)
         return
 
+    if args.command == "update":
+        update_argv: list[str] = []
+        if args.config:
+            update_argv.extend(["--config", args.config])
+        update_main(update_argv)
+        return
+
     # Default to build for backwards compatibility.
     if len(sys.argv) > 1 and sys.argv[1] in (
         "--production",

{fr_docs-3.1.0 → fr_docs-3.3.0}/fr_docs/build.py

@@ -68,6 +68,126 @@ def _best_zstd_level(raw: bytes, configured: int) -> int:
     return best_level
 
 
+def _script_version_hash(script_path):
+    """Return (version, sha1_hex) for a script.js file.
+
+    Looks for a ``// version: <n>`` comment on the first line. If no version
+    is found, returns (0, sha1_of_content).
+    """
+    try:
+        text = script_path.read_text(encoding="utf-8")
+    except OSError:
+        return 0, ""
+    first_line = text.split("\n", 1)[0].strip()
+    m = re.match(r"//\s*version:\s*(\d+)", first_line)
+    version = int(m.group(1)) if m else 0
+    return version, xxhash.xxh3_128_hexdigest(text.encode("utf-8"))
+
+
+def _git_script_versions(repo_root, script_rel_path):
+    """Return a list of (version, sha1) for every historical version of the
+    script found in the git tree.
+
+    The script's own ``// version: <n>`` comment is the source of truth;
+    if a blob in git history has no version comment, its sha1 is still
+    recorded so we can detect whether the local file matches a known
+    historical version.
+    """
+    versions = []
+    seen_blobs = set()
+    try:
+        out = subprocess.check_output(
+            ["git", "log", "--all", "--pretty=format:%H", "--", script_rel_path],
+            cwd=repo_root,
+            text=True,
+            stderr=subprocess.DEVNULL,
+        ).strip()
+    except (subprocess.CalledProcessError, OSError):
+        return versions
+
+    for commit in out.splitlines():
+        commit = commit.strip()
+        if not commit:
+            continue
+        try:
+            blob = subprocess.check_output(
+                ["git", "rev-parse", f"{commit}:{script_rel_path}"],
+                cwd=repo_root,
+                text=True,
+                stderr=subprocess.DEVNULL,
+            ).strip()
+        except (subprocess.CalledProcessError, OSError):
+            continue
+        if not blob or blob in seen_blobs:
+            continue
+        seen_blobs.add(blob)
+        try:
+            content = subprocess.check_output(
+                ["git", "show", blob],
+                cwd=repo_root,
+                stderr=subprocess.DEVNULL,
+            ).decode("utf-8", errors="replace")
+        except (subprocess.CalledProcessError, OSError):
+            continue
+        first_line = content.split("\n", 1)[0].strip()
+        m = re.match(r"//\s*version:\s*(\d+)", first_line)
+        ver = int(m.group(1)) if m else 0
+        h = xxhash.xxh3_128_hexdigest(content.encode("utf-8"))
+        versions.append((ver, h))
+
+    return versions
+
+
+def _resolve_script_version(repo_root, script_rel_path, local_path):
+    """Resolve the version and content to use for script.js.
+
+    Returns (version, content_text) where content_text is the script to write
+    to the output directory. If the local script has no version comment but
+    its hash matches a known historical version, the historical version
+    number is used. If the remote (repo HEAD) has a higher version, the
+    remote content is used instead.
+    """
+    local_version, local_hash = _script_version_hash(local_path)
+    remote_version, remote_hash = _script_version_hash(
+        Path(repo_root, script_rel_path)
+    )
+
+    # If local has no version but matches a known historical blob, adopt
+    # that version number so future comparisons work.
+    if local_version == 0:
+        hist = _git_script_versions(repo_root, script_rel_path)
+        for ver, h in hist:
+            if h == local_hash and ver > 0:
+                local_version = ver
+                break
+
+    # If remote is newer, use remote content.
+    if remote_version > local_version:
+        try:
+            content = Path(repo_root, script_rel_path).read_text(encoding="utf-8")
+            return remote_version, content
+        except OSError:
+            pass
+
+    # Otherwise use local content.
+    try:
+        content = local_path.read_text(encoding="utf-8")
+    except OSError:
+        content = ""
+    return local_version, content
+
+
+def _write_script_js(out_path, version, content):
+    """Write script.js with a ``// version: <n>`` first line."""
+    if not content:
+        return
+    first_line = content.split("\n", 1)[0].strip()
+    if re.match(r"//\s*version:\s*\d+", first_line):
+        out_path.write_text(content, encoding="utf-8")
+    else:
+        out_path.write_text(f"// version: {version}\n{content}", encoding="utf-8")
+
+
 def _minify_static_asset(config, src: Path, dst: Path, name: str) -> None:
     """Minify a static asset in-place (JS via terser, CSS via html-minifier).
 
@@ -380,6 +500,12 @@ def main(argv=None) -> None:
         print(f"   Site prefix: {normalized_site_prefix(config)}")
     print()
 
+    # Auto-update resources if enabled
+    if config.get("build", {}).get("auto_update", True):
+        from .update import update_resources
+        update_resources(config)
+        print()
+
     # Collect source files for code references
     search_includes = search_include_config(config)
     if feature_enabled(config, "code_references") or (
@@ -402,7 +528,7 @@ def main(argv=None) -> None:
         "symbol_index.json",
     ):
         Path(config["_out_dir"], legacy_name).unlink(missing_ok=True)
-    for name in ("favicon.svg", "fonts.css", "script.js", "style.css"):
+    for name in ("favicon.svg", "fonts.css", "style.css"):
         src = docs_path / name
         dst = Path(config["_out_dir"]) / name
 
@@ -416,6 +542,26 @@ def main(argv=None) -> None:
         except OSError as e:
             print(f"OSError: {e}")
 
+    # script.js: check version comment and update from repo if needed
+    repo_root = Path(config["_docs_dir"]).resolve().parent
+    script_rel = str(Path(config["_docs_dir"]).resolve().relative_to(repo_root)) + "/script.js"
+    local_script = docs_path / "script.js"
+    out_script = Path(config["_out_dir"]) / "script.js"
+
+    if local_script.exists():
+        version, content = _resolve_script_version(repo_root, script_rel, local_script)
+        if config.get("production", False):
+            # Minify the resolved content
+            _minify_static_asset(config, local_script, out_script, "script.js")
+            # Re-write version header on minified output
+            minified = out_script.read_text(encoding="utf-8")
+            first_line = minified.split("\n", 1)[0].strip()
+            if not re.match(r"//\s*version:\s*\d+", first_line):
+                out_script.write_text(f"// version: {version}\n{minified}", encoding="utf-8")
+        else:
+            _write_script_js(out_script, version, content)
+        print(f"   script.js: version {version}")
+
     # Copy locally-fetched fonts (if present) so the site doesn't need
     # to reach out to fonts.gstatic.com. fonts.css is minified along
     # with style.css below.

{fr_docs-3.1.0 → fr_docs-3.3.0}/fr_docs/config.py

@@ -28,6 +28,7 @@ DEFAULT_CONFIG = {
         "zstd_level": 22,
         "search_index_filename": "search_index.zst",
         "git_meta_filename": "git_meta.zst",
+        "auto_update": True,
     },
     "versioning": {
         "commit_message_pattern": r"^\s*([0-9]+[A-Za-z])\s*[-:—–]\s*(.+)",

{fr_docs-3.1.0 → fr_docs-3.3.0}/fr_docs/git.py

@@ -86,9 +86,8 @@ def _build_slug_last_commits(slugs, config, repo_root):
         out = subprocess.check_output(
             ["git", "log", "-1", "--pretty=format:%H", "--", src],
             cwd=repo_root,
-            text=True,
             stderr=subprocess.DEVNULL,
-        ).strip()
+        ).decode("utf-8", errors="replace").strip()
 
         if out and re.fullmatch(r"[0-9a-f]{7,40}", out):
             slug_last_commit[slug] = out
@@ -114,8 +113,8 @@ def collect_git_metadata(config):
     remote_url = subprocess.check_output(
         ["git", "remote", "get-url", "origin"],
         cwd=repo_root,
-        text=True,
-    ).strip()
+        stderr=subprocess.DEVNULL,
+    ).decode("utf-8", errors="replace").strip()
 
     if m := re.search(r"github.com[:/](.+?)(?:\.git)?$", remote_url):
         git_meta["repo"] = m[1]
@@ -123,8 +122,8 @@ def collect_git_metadata(config):
     log_out = subprocess.check_output(
         ["git", "log", "--pretty=format:%H\x01%s", "--reverse"],
         cwd=repo_root,
-        text=True,
-    )
+        stderr=subprocess.DEVNULL,
+    ).decode("utf-8", errors="replace")
 
     commits, versions = _parse_commit_log(log_out)
     git_meta["commits"] = commits
@@ -152,9 +151,8 @@ def collect_git_metadata(config):
         ]
         + [src_map_path(config).replace("{slug}", s) for s in slugs],
         cwd=repo_root,
-        text=True,
         stderr=subprocess.DEVNULL,
-    )
+    ).decode("utf-8", errors="replace")
 
     git_meta["pages_by_commit"] = _build_pages_by_commit(out, slugs)
     git_meta["slug_last_commit"] = _build_slug_last_commits(slugs, config, repo_root)

{fr_docs-3.1.0 → fr_docs-3.3.0}/fr_docs/html_pipeline.py

@@ -43,7 +43,7 @@ from .syntax import (
     process_blockquotes,
 )
 from .template import TEMPLATE, build_toc_sidebar
-from .utils import normalized_site_prefix, output_href
+from .utils import normalized_site_prefix, output_href, output_asset_href
 
 
 def _determine_tagged_sections(config):
@@ -128,7 +128,7 @@ def _get_search_preloads_html():
 def _render_template_placeholders(config):
     """Extract common template placeholders from config."""
     return {
-        "site_prefix": output_href("", config),
+        "site_prefix": output_asset_href("", config),
         "page_title": "",
         "project_name": project_name(config),
         "og_title": "",

fr_docs-3.3.0/fr_docs/update.py

@@ -0,0 +1,135 @@
+"""Update fr-docs resources (script.js, style.css, fonts) from the repo."""
+
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from .config import load_config
+from .config_accessors import out_dir, project_name, src_dir as config_src_dir
+from .build import (
+    _resolve_script_version,
+    _write_script_js,
+    _minify_static_asset,
+    _script_version_hash,
+)
+
+
+def _fetch_remote(repo_root, rel_path):
+    """Fetch a file from the fr-docs repo via git show HEAD:path."""
+    try:
+        return subprocess.check_output(
+            ["git", "show", f"HEAD:{rel_path}"],
+            cwd=repo_root,
+            stderr=subprocess.DEVNULL,
+        ).decode("utf-8", errors="replace")
+    except (subprocess.CalledProcessError, OSError):
+        return None
+
+
+def _git_current_commit(repo_root):
+    try:
+        return subprocess.check_output(
+            ["git", "rev-parse", "HEAD"],
+            cwd=repo_root,
+            stderr=subprocess.DEVNULL,
+        ).decode("utf-8", errors="replace").strip()
+    except (subprocess.CalledProcessError, OSError):
+        return None
+
+
+def _git_remote_url(repo_root):
+    try:
+        return subprocess.check_output(
+            ["git", "remote", "get-url", "origin"],
+            cwd=repo_root,
+            stderr=subprocess.DEVNULL,
+        ).decode("utf-8", errors="replace").strip()
+    except (subprocess.CalledProcessError, OSError):
+        return None
+
+
+def _is_fr_docs_repo(repo_root):
+    """Return True if the repo is the fr-docs repo itself."""
+    url = _git_remote_url(repo_root) or ""
+    return "Omena0/fr-docs" in url or "omena0/fr-docs" in url.lower()
+
+
+def update_resources(config):
+    """Update script.js, style.css, favicon.svg, and fonts from the fr-docs repo.
+
+    Only runs when the current repo IS the fr-docs repo (so we can read
+    the source files from git). For downstream repos, the resources are
+    pulled from PyPI via the `fr-docs` package or copied from the docs/
+    directory.
+    """
+    docs_path = Path(config["_docs_dir"]).resolve()
+    repo_root = docs_path.parent
+    if not _is_fr_docs_repo(repo_root):
+        print("   Not the fr-docs repo; skipping remote resource update.")
+        return
+
+    resources = ["script.js", "style.css", "favicon.svg"]
+    updated = []
+    for name in resources:
+        rel = f"docs/{name}"
+        remote = _fetch_remote(repo_root, rel)
+        if remote is None:
+            continue
+        local_path = docs_path / name
+        if name == "script.js":
+            version, content = _resolve_script_version(repo_root, rel, local_path)
+            _write_script_js(local_path, version, content)
+            updated.append(f"{name} (v{version})")
+        else:
+            local_path.write_text(remote, encoding="utf-8")
+            updated.append(name)
+
+    # Update fonts
+    fonts_dir = docs_path / "fonts"
+    if fonts_dir.is_dir():
+        remote_fonts = _fetch_remote(repo_root, "docs/fonts")
+        # Can't fetch a directory; instead list remote files via git ls-tree
+        try:
+            out = subprocess.check_output(
+                ["git", "ls-tree", "-r", "--name-only", "HEAD", "docs/fonts"],
+                cwd=repo_root,
+                stderr=subprocess.DEVNULL,
+            ).decode("utf-8", errors="replace")
+            for line in out.splitlines():
+                fname = Path(line).name
+                content = _fetch_remote(repo_root, line)
+                if content is not None:
+                    (fonts_dir / fname).write_text(content, encoding="utf-8")
+                    updated.append(f"fonts/{fname}")
+        except (subprocess.CalledProcessError, OSError):
+            pass
+
+    if updated:
+        print(f"   Updated: {', '.join(updated)}")
+    else:
+        print("   No resources updated.")
+
+
+def main(argv=None) -> None:
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        prog="fr-docs update",
+        description="Update fr-docs resources (script.js, style.css, fonts) from the repo.",
+    )
+    parser.add_argument(
+        "--config",
+        help="Path to the configuration JSON file.",
+    )
+    args = parser.parse_args(argv)
+
+    config = load_config(args.config)
+    print(f"🔄 Updating {project_name(config)} resources...")
+    update_resources(config)
+    print("✅ Update complete.")
+
+
+if __name__ == "__main__":
+    main()

{fr_docs-3.1.0 → fr_docs-3.3.0}/fr_docs/utils.py

@@ -21,4 +21,15 @@ def output_href(path, config):
 
 
 def output_site_prefix(config: dict) -> str:
-    return normalized_site_prefix(config) if config.get("production", False) else ""
+    return normalized_site_prefix(config) if config.get("production", False) else "/"
+
+
+def output_asset_href(path, config):
+    """Return a root-relative href for a static asset.
+
+    Static assets (CSS, JS, favicon, fonts) must resolve from any page
+    depth, so they always use a root-relative path (e.g. ``/style.css``).
+    """
+    clean = str(path or "").lstrip("/")
+    prefix = normalized_site_prefix(config)
+    return prefix + clean if prefix else "/" + clean

{fr_docs-3.1.0 → fr_docs-3.3.0}/fr_docs.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fr-docs
-Version: 3.1.0
+Version: 3.3.0
 Summary: Fast static documentation generator with search, versioning, and zero-config setup
 Author: Omena0
 License: # PolyForm Noncommercial License 1.0.0

{fr_docs-3.1.0 → fr_docs-3.3.0}/fr_docs.egg-info/SOURCES.txt

@@ -15,6 +15,7 @@ fr_docs/search.py
 fr_docs/slug.py
 fr_docs/syntax.py
 fr_docs/template.py
+fr_docs/update.py
 fr_docs/utils.py
 fr_docs.egg-info/PKG-INFO
 fr_docs.egg-info/SOURCES.txt

{fr_docs-3.1.0 → fr_docs-3.3.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fr-docs"
-version = "3.1.0"
+version = "3.3.0"
 description = "Fast static documentation generator with search, versioning, and zero-config setup"
 readme = "README.md"
 requires-python = ">=3.14"