fr-docs 2.1.6__tar.gz → 2.3.0__tar.gz

{fr_docs-2.1.6 → fr_docs-2.3.0}/PKG-INFO

@@ -1,7 +1,8 @@
 Metadata-Version: 2.4
 Name: fr-docs
-Version: 2.1.6
+Version: 2.3.0
 Summary: Fast static documentation generator with search, versioning, and zero-config setup
+Author: Omena0
 License: # PolyForm Noncommercial License 1.0.0
         
         <https://polyformproject.org/licenses/noncommercial/1.0.0>
@@ -134,10 +135,91 @@ License: # PolyForm Noncommercial License 1.0.0
         **Use** means anything you do with the software requiring one
         of your licenses.
         
+Project-URL: Homepage, https://omena0.dev/fr-docs/
+Project-URL: Documentation, https://omena0.dev/fr-docs/
+Project-URL: Repository, https://github.com/Omena0/fr-docs
+Project-URL: Issues, https://github.com/Omena0/fr-docs/issues
+Keywords: documentation,documentation-generator,static-site-generator,markdown,github-pages,static-site,docs
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Build Tools
 Requires-Python: >=3.14
+Description-Content-Type: text/markdown
 License-File: LICENSE.md
 Requires-Dist: fastpylight>=0.1.18
 Requires-Dist: markdown
 Requires-Dist: xxhash>=4.0.1
 Requires-Dist: zstandard
 Dynamic: license-file
+
+
+# Fr-docs
+
+Generate fast, fully featured, modern documentation pages from markdown for GitHub pages and static hosting.
+
+[![Lint](https://github.com/Omena0/fr-docs/actions/workflows/lint.yml/badge.svg)](https://github.com/Omena0/fr-docs/actions/workflows/lint.yml)
+[![Docs](https://github.com/Omena0/fr-docs/actions/workflows/pages.yml/badge.svg)](https://github.com/Omena0/fr-docs/actions/workflows/pages.yml)
+[![PyPi](https://github.com/Omena0/fr-docs/actions/workflows/publish.yml/badge.svg)](https://github.com/Omena0/fr-docs/actions/workflows/publish.yml)
+[![CodeQL](https://github.com/Omena0/fr-docs/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/Omena0/fr-docs/actions/workflows/github-code-scanning/codeql)
+
+## Documentation
+
+- [Getting Started](https://omena0.dev/fr-docs/)
+- [Installation](https://omena0.dev/fr-docs/installation)
+- [Quickstart](https://omena0.dev/fr-docs/quickstart)
+- [Configuration](https://omena0.dev/fr-docs/config.json)
+- [Showcase](https://omena0.dev/fr-docs/showcase)
+- [Pagespeed](https://omena0.dev/fr-docs/pagespeed) — performance metrics
+
+## Overview
+
+Fr-docs is a generic, configurable documentation builder for Python projects. It converts Markdown source files into a searchable, optimized static HTML site with zero-config setup.
+
+### Key Features
+
+- **Config-driven**: All settings defined in `config.json`
+  - Project name, URL, description, and sidebar structure
+  - Search, code references, auto-linking, and related pages
+  - Build options: workers, minification, zstd level, and HTML optimization
+
+- **Zero-config setup**: Works out of the box with sensible defaults
+- **Search**: Full-text search with Zstandard-compressed index
+  - Symbol-level search across all source files
+  - File index for browsing source code
+  - Per-file source highlights with caching
+
+- **Optimized**: HTML minification, critical CSS/JS inlining, Zstd compression
+  - Critical CSS extracted and inlined for both mobile and desktop viewports
+  - JavaScript and CSS minified with `terser` and `html-minifier-next`
+  - Zstd-compressed search index, source files, highlights, and metadata
+  - Adaptive zstd level selection (scans 1..configured, picks the smallest)
+
+- **Multi-environment**: Different configs for production, staging, development
+- **Parallel builds**: Threaded page generation for faster builds
+- **Git integration**: Automatic metadata extraction from git commits
+  - Version options derived from commit messages (e.g. `4D - fix bug` → `4.4.0`)
+  - Commit SHA and message embedded in the version selector
+
+- **Local font serving**: Fonts downloaded at build time and served from the site's own origin
+  - No third-party font round-trips or 404s when Google changes the URL scheme
+  - `font-display: swap` with metric-compatible `font-ascent-descent` fallbacks
+  - Primary body font weight preloaded for faster first paint
+
+- **Sidebar**: Collapsible sections with auto-expansion
+  - The section containing the current page is expanded on load
+  - Single-page sections and single-section sites are expanded by default
+
+- **Inline copy commands**: Prefix inline code with `c` to create copy-on-click links
+- **Code references**: Auto-link bare filename references to their source files
+- **Backlinks and related pages**: Automatically generated navigation between related content
+
+### Projects that use fr-docs
+
+- [Fr-docs](https://omena0.dev/fr-docs/)
+- [PyJavaBridge](https://omena0.dev/PyJavaBridge)

{fr_docs-2.1.6 → fr_docs-2.3.0}/README.md

@@ -15,6 +15,7 @@ Generate fast, fully featured, modern documentation pages from markdown for GitH
 - [Quickstart](https://omena0.dev/fr-docs/quickstart)
 - [Configuration](https://omena0.dev/fr-docs/config.json)
 - [Showcase](https://omena0.dev/fr-docs/showcase)
+- [Pagespeed](https://omena0.dev/fr-docs/pagespeed) — performance metrics
 
 ## Overview
 
@@ -23,12 +24,40 @@ Fr-docs is a generic, configurable documentation builder for Python projects. It
 ### Key Features
 
 - **Config-driven**: All settings defined in `config.json`
+  - Project name, URL, description, and sidebar structure
+  - Search, code references, auto-linking, and related pages
+  - Build options: workers, minification, zstd level, and HTML optimization
+
 - **Zero-config setup**: Works out of the box with sensible defaults
 - **Search**: Full-text search with Zstandard-compressed index
+  - Symbol-level search across all source files
+  - File index for browsing source code
+  - Per-file source highlights with caching
+
 - **Optimized**: HTML minification, critical CSS/JS inlining, Zstd compression
+  - Critical CSS extracted and inlined for both mobile and desktop viewports
+  - JavaScript and CSS minified with `terser` and `html-minifier-next`
+  - Zstd-compressed search index, source files, highlights, and metadata
+  - Adaptive zstd level selection (scans 1..configured, picks the smallest)
+
 - **Multi-environment**: Different configs for production, staging, development
 - **Parallel builds**: Threaded page generation for faster builds
 - **Git integration**: Automatic metadata extraction from git commits
+  - Version options derived from commit messages (e.g. `4D - fix bug` → `4.4.0`)
+  - Commit SHA and message embedded in the version selector
+
+- **Local font serving**: Fonts downloaded at build time and served from the site's own origin
+  - No third-party font round-trips or 404s when Google changes the URL scheme
+  - `font-display: swap` with metric-compatible `font-ascent-descent` fallbacks
+  - Primary body font weight preloaded for faster first paint
+
+- **Sidebar**: Collapsible sections with auto-expansion
+  - The section containing the current page is expanded on load
+  - Single-page sections and single-section sites are expanded by default
+
+- **Inline copy commands**: Prefix inline code with `c` to create copy-on-click links
+- **Code references**: Auto-link bare filename references to their source files
+- **Backlinks and related pages**: Automatically generated navigation between related content
 
 ### Projects that use fr-docs
 

{fr_docs-2.1.6 → fr_docs-2.3.0}/fr_docs/__main__.py

@@ -1,8 +1,8 @@
 """Entry point for fr-docs CLI.
 
 Usage:
-    python -m fr_docs build [--production] [--config CONFIG]
-    fr-docs build [--production] [--config CONFIG]
+    python -m fr_docs build [--production] [--symlink] [--config CONFIG]
+    fr-docs build [--production] [--symlink] [--config CONFIG]
     python -m fr_docs init [--dir DIR]
     fr-docs init [--dir DIR]
 """
@@ -27,6 +27,14 @@ def main():
         action="store_true",
         help="Rewrite internal links to site-root absolute paths for deployed docs.",
     )
+    build_parser.add_argument(
+        "--symlink",
+        action="store_true",
+        help="Create a {site_prefix}/ symlink dir under site/ so a local "
+        "production build can be opened in a browser. Off by default: in "
+        "CI the whole docs/site/ tree is deployed as-is, and a nested "
+        "fr-docs/ symlink folder would show up as omena0.dev/fr-docs/fr-docs/.",
+    )
     build_parser.add_argument(
         "--config",
         help="Path to the configuration JSON file.",
@@ -51,6 +59,8 @@ def main():
         build_argv = []
         if args.production:
             build_argv.append("--production")
+        if args.symlink:
+            build_argv.append("--symlink")
         if args.config:
             build_argv.extend(["--config", args.config])
         build_main(build_argv)
@@ -60,6 +70,7 @@ def main():
         # Default to build for backwards compatibility
         if len(sys.argv) > 1 and sys.argv[1] in (
             "--production",
+            "--symlink",
             "--config",
             "--help",
             "-h",

{fr_docs-2.1.6 → fr_docs-2.3.0}/fr_docs/build.py

@@ -30,7 +30,7 @@ from .config_accessors import (
     zstd_level,
 )
 from .git import build_version_options, collect_git_metadata
-from .html_pipeline import build_page
+from .html_pipeline import build_page, minify_all_pages, optimize_all_pages
 from .search import build_search_index, search_include_config
 from .slug import (
     build_slug_page_keys,
@@ -45,6 +45,25 @@ def _compute_hash(data: str) -> str:
     return xxhash.xxh3_128_hexdigest(data.encode("utf-8"))
 
 
+def _best_zstd_level(raw: bytes, configured: int) -> int:
+    """Pick the zstd compression level that minimizes compressed size.
+
+    Scans levels 1..configured and returns the one producing the smallest
+    output, breaking ties toward the lower level so decompression stays
+    fast. Level 22 is very slow and rarely beats lower levels on real
+    payloads, so this avoids paying for it when it doesn't help.
+    """
+    if len(raw) < 1024:
+        return min(configured, 19)
+
+    best_level, best_size = 1, len(zstandard.ZstdCompressor(level=1).compress(raw))
+    for level in range(2, configured + 1):
+        size = len(zstandard.ZstdCompressor(level=level).compress(raw))
+        if size < best_size:
+            best_level, best_size = level, size
+    return best_level
+
+
 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).
 
@@ -166,7 +185,9 @@ def _write_zstd_json(config, filename, value):
         if src.exists():
             return len(raw), src.stat().st_size
 
-    compressed = zstandard.ZstdCompressor(level=zstd_level(config)).compress(raw)
+    compressed = zstandard.ZstdCompressor(
+        level=_best_zstd_level(raw, zstd_level(config))
+    ).compress(raw)
     path = Path(config["_out_dir"]) / filename
     path.write_bytes(compressed)
     cache.update_cache(filename, raw_hash)
@@ -336,6 +357,14 @@ def main(argv=None):
         action="store_true",
         help="Rewrite internal links to site-root absolute paths for deployed docs.",
     )
+    parser.add_argument(
+        "--symlink",
+        action="store_true",
+        help="Create a {site_prefix}/ symlink dir under site/ so a local "
+        "production build can be opened in a browser. Off by default: in "
+        "CI the whole docs/site/ tree is deployed as-is, and a nested "
+        "fr-docs/ symlink folder would show up as omena0.dev/fr-docs/fr-docs/.",
+    )
     parser.add_argument(
         "--config",
         help="Path to the configuration JSON file.",
@@ -375,7 +404,7 @@ def main(argv=None):
         "symbol_index.json",
     ):
         Path(config["_out_dir"], legacy_name).unlink(missing_ok=True)
-    for name in ("favicon.svg", "script.js", "style.css"):
+    for name in ("favicon.svg", "fonts.css", "script.js", "style.css"):
         src = docs_path / name
         dst = Path(config["_out_dir"]) / name
 
@@ -389,6 +418,18 @@ def main(argv=None):
         except OSError as e:
             print(f"OSError: {e}")
 
+    # 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.
+    fonts_dir = docs_path / "fonts"
+    if fonts_dir.is_dir():
+        out_fonts = Path(config["_out_dir"]) / "fonts"
+        out_fonts.mkdir(parents=True, exist_ok=True)
+        for f in fonts_dir.iterdir():
+            if f.is_file():
+                shutil.copy2(f, out_fonts / f.name)
+        print(f"   Copied {len(list(out_fonts.iterdir()))} font files")
+
     slugs = get_all_slugs(config)
 
     # Also check for any .md files not in the sidebar
@@ -413,8 +454,11 @@ def main(argv=None):
 
     # Compress search index
     search_json = json.dumps(search_index, separators=(",", ":"))
-    cctx = zstandard.ZstdCompressor(level=zstd_level(config))
-    compressed = cctx.compress(search_json.encode("utf-8"))
+    search_raw = search_json.encode("utf-8")
+    cctx = zstandard.ZstdCompressor(
+        level=_best_zstd_level(search_raw, zstd_level(config))
+    )
+    compressed = cctx.compress(search_raw)
     search_index_path = os.path.join(config["_out_dir"], search_index_filename(config))
     os.makedirs(os.path.dirname(search_index_path), exist_ok=True)
     with open(search_index_path, "wb") as sf:
@@ -432,7 +476,7 @@ def main(argv=None):
         )
 
     print(
-        f"   Search index: {len(search_json.encode('utf-8')):,} bytes → {len(compressed):,} zstd ({100 * len(compressed) / len(search_json.encode('utf-8')):.1f}%)"
+        f"   Search index: {len(search_raw):,} bytes → {len(compressed):,} zstd ({100 * len(compressed) / len(search_raw):.1f}%)"
     )
 
     # Save source files for code references
@@ -472,7 +516,7 @@ def main(argv=None):
                     "utf-8"
                 )
                 compressed = zstandard.ZstdCompressor(
-                    level=zstd_level(config)
+                    level=_best_zstd_level(raw, zstd_level(config))
                 ).compress(raw)
                 highlight_cache_file.parent.mkdir(parents=True, exist_ok=True)
                 highlight_cache_file.write_bytes(compressed)
@@ -557,6 +601,45 @@ def main(argv=None):
     else:
         print("No pages found to build.")
 
+    if config.get("production", False):
+        print()
+        print("🔧 Optimizing HTML (critical CSS inlining)...")
+        try:
+            optimize_all_pages(config)
+            print("   ✓ Critical CSS inlined")
+        except Exception as e:  # noqa: BLE001
+            print(f"   ✗ Critical failed: {e}")
+
+        print("🔧 Minifying HTML...")
+        try:
+            minify_all_pages(config)
+            print("   ✓ HTML minified")
+        except Exception as e:  # noqa: BLE001
+            print(f"   ✗ Minification failed: {e}")
+
+# Create a {site_prefix}/ directory under site/ and symlink every
+        # file into it, so a production build works locally (the HTML
+        # references absolute paths like /fr-docs/style.css). Without
+        # this, running `python -m fr_docs build --production` and then
+        # opening site/index.html in a browser would 404 on every asset.
+        #
+        # Off by default: in CI the whole docs/site/ tree is deployed
+        # as-is, and a nested fr-docs/ symlink folder would show up as
+        # omena0.dev/fr-docs/fr-docs/. Pass --symlink to enable it.
+        if args.symlink:
+            prefix = normalized_site_prefix(config).strip("/") or "fr-docs"
+            prefix_dir = Path(config["_out_dir"]) / prefix
+            try:
+                if prefix_dir.is_symlink() or prefix_dir.exists():
+                    shutil.rmtree(prefix_dir, ignore_errors=True)
+                prefix_dir.mkdir(parents=True, exist_ok=True)
+                for f in sorted(Path(config["_out_dir"]).iterdir()):
+                    if f.is_file() and not f.name.startswith("."):
+                        (prefix_dir / f.name).symlink_to(f.resolve())
+                print(f"   ✓ Symlinked {len(list(prefix_dir.iterdir()))} files into {prefix}/")
+            except OSError as e:
+                print(f"   ✗ Failed to create {prefix}/ symlinks: {e}")
+
     print(f"\n✅ Built {built} pages")
 
 

{fr_docs-2.1.6 → fr_docs-2.3.0}/fr_docs/html_pipeline.py

@@ -77,7 +77,7 @@ def _render_template_placeholders(config):
     def _get_header_search_html():
         if not feature_enabled(config, "search"):
             return ""
-        return """<svg class="header-search-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/></svg>
+        return """<svg class="header-search-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" width="24" height="24" aria-hidden="true"><circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/></svg>
       <input type="text" id="header-search" placeholder="Search docs… (Ctrl+K)" autocomplete="off">
       <div id="search-results" class="search-results"></div>"""
 
@@ -149,44 +149,13 @@ def absolutize_links(html_text, page_url, config):
 
 
 def optimize_html(html_input, config):
-    if not config.get("production", False):
-        return html_input
-    if not cfg_optimize_html(config):
-        return html_input
-
-    with tempfile.NamedTemporaryFile("w+", suffix=".html", delete=False) as f_in:
-        f_in.write(html_input)
-        in_path = Path(f_in.name)
-
-    cmd = [
-        "npx",
-        "critical",
-        str(in_path),
-        "--inline",
-        "--width",
-        "1920",
-        "--height",
-        "1080",
-    ]
-
-    result = subprocess.run(cmd, capture_output=True, text=True, check=False)
-
-    try:
-        if result.returncode != 0:
-            raise RuntimeError(f"Critical failed:\n{result.stderr}")
+    """Legacy single-file optimizer — kept for backwards compat.
 
-        optimized_html = result.stdout
-
-        if "</html>" not in optimized_html:
-            raise RuntimeError("Critical output looks truncated/corrupted")
-
-        return optimized_html
-
-    finally:
-        try:
-            in_path.unlink()
-        except OSError:
-            pass
+    critical only resolves <link rel=stylesheet> URLs when run on a
+    directory, so this is a no-op in production. Use optimize_all_pages
+    instead.
+    """
+    return html_input
 
 
 def minify_html(html_input, config):
@@ -344,21 +313,12 @@ def build_page(slug, config, slug_page_keys):
 
     out_html = TEMPLATE.format(**placeholders)
 
-    try:
-        out_html = optimize_html(out_html, config)
-    except Exception as e:  # noqa: BLE001
-        logger.warning(f"Failed to optimize HTML: {e}")
-
-    try:
-        out_html = minify_html(out_html, config)
-    except Exception as e:  # noqa: BLE001
-        logger.warning(f"Failed to minify HTML: {e}")
-
     if config.get("production", False):
         page_url = (
             f"https://docs.local{output_href(slug_output_name(slug, config), config)}"
         )
         out_html = absolutize_links(out_html, page_url, config)
+        out_html = add_internal_prefetch_links(out_html, config)
 
     out_name = slug_output_name(slug, config)
     out_path = os.path.join(config["_out_dir"], out_name)
@@ -366,6 +326,185 @@ def build_page(slug, config, slug_page_keys):
         f.write(out_html)
 
 
+def optimize_all_pages(config):
+    """Inline critical-path CSS into every production HTML page.
+
+    critical only resolves <link rel=stylesheet> URLs when run on a
+    single HTML file with the static engine (directory mode reports
+    "no stylesheets discovered" regardless of engine). Running it on a
+    single temp file reports "no stylesheets discovered" and silently
+    passes through — which on a slow 4G connection means FCP is gated
+    by the full CSS download (~4s for 7.6KB at 1.6Mbps).
+
+    Must be called once after all pages are written, not from within
+    build_page (which runs in a thread pool).
+    """
+    if not config.get("production", False):
+        return
+    if not cfg_optimize_html(config):
+        return
+
+    out_dir = Path(config["_out_dir"]).resolve()
+    if not out_dir.is_dir():
+        return
+
+    # critical only follows relative stylesheet URLs from each HTML
+    # file's location. The production template uses absolute paths
+    # (e.g. href=/fr-docs/style.css), so rewrite them to relative
+    # paths first, run critical, then restore the absolute paths in
+    # the inlined output.
+    site_prefix = normalized_site_prefix(config)
+    stripped_prefix = site_prefix.rstrip("/") if site_prefix and site_prefix != "/" else None
+    backed_up = []
+
+    try:
+        if stripped_prefix:
+            # Match both quoted (href="/fr-docs/style.css") and unquoted
+            # (href=/fr-docs/style.css) forms. The minifier strips quotes,
+            # so both must be supported.
+            prefix_pat = re.compile(
+                rf'href=(["\']?){re.escape(stripped_prefix)}/([^"\'\s>]+)\1'
+            )
+            for html_file in out_dir.glob("*.html"):
+                raw = html_file.read_text(encoding="utf-8")
+                backup = out_dir / f".critical_orig_{html_file.stem}.html"
+                backup.write_text(raw, encoding="utf-8")
+                backed_up.append(backup)
+                # Strip the site prefix so href=/fr-docs/style.css
+                # becomes href=style.css (relative to the HTML file).
+                rewritten = prefix_pat.sub(
+                    lambda m: f'href={m.group(1)}{m.group(2)}{m.group(1)}',
+                    raw,
+                )
+                html_file.write_text(rewritten, encoding="utf-8")
+
+        # Run critical per-file with the static engine (the only engine
+        # that resolves relative stylesheet URLs from a single file).
+        # Use --dimensions to render for both mobile (390x844, Moto G
+        # Power) and desktop (1920x1080) so the inlined critical CSS
+        # includes the @media(width<=640px) rules that mobile needs.
+        for html_file in out_dir.glob("*.html"):
+            cmd = [
+                "npx",
+                "critical",
+                str(html_file),
+                "--inline",
+                "--engine",
+                "static",
+                "--dimensions",
+                "390x844,1920x1080",
+                "--width",
+                "1920",
+                "--height",
+                "1080",
+            ]
+
+            result = subprocess.run(
+                cmd, capture_output=True, text=True, check=False, cwd=str(out_dir)
+            )
+            if result.returncode != 0:
+                raise RuntimeError(
+                    f"Critical failed for {html_file.name}:\n{result.stderr}"
+                )
+
+            optimized = result.stdout
+            if "</html>" not in optimized:
+                raise RuntimeError(
+                    f"Critical output for {html_file.name} looks truncated"
+                )
+
+            html_file.write_text(optimized, encoding="utf-8")
+
+    finally:
+        # Restore the original absolute-path HTML for any page critical
+        # didn't inline (e.g. it failed or skipped).
+        for backup in backed_up:
+            target = out_dir / f"{backup.stem.replace('.critical_orig_', '')}.html"
+            if target.exists() and backup.exists():
+                try:
+                    target_content = target.read_text(encoding="utf-8")
+                    # Only restore if critical didn't inline CSS
+                    if "data-critical" not in target_content:
+                        target.write_text(
+                            backup.read_text(encoding="utf-8"),
+                            encoding="utf-8",
+                        )
+                except OSError:
+                    pass
+            try:
+                backup.unlink()
+            except OSError:
+                pass
+
+
+def minify_all_pages(config):
+    """Minify every production HTML page after critical has inlined CSS."""
+    if not config.get("production", False):
+        return
+    if not cfg_minify_html(config):
+        return
+
+    out_dir = Path(config["_out_dir"]).resolve()
+    if not out_dir.is_dir():
+        return
+
+    for html_file in sorted(out_dir.glob("*.html")):
+        try:
+            raw = html_file.read_text(encoding="utf-8")
+            minified = minify_html(raw, config)
+            html_file.write_text(minified, encoding="utf-8")
+        except Exception as e:  # noqa: BLE001
+            logger.warning(f"Failed to minify {html_file.name}: {e}")
+
+
+def add_internal_prefetch_links(html_text, config):
+    """Add rel="prefetch" to every internal page link in production HTML.
+
+    Prefetching the whole site up front is cheap here (a handful of small
+    pages) and makes navigation instant. We deliberately avoid
+    <link rel="preload" as="document">: Chrome's preload scanner rejects
+    dynamically-injected document preloads, and rel="prefetch" is the
+    correct hint for "fetch this page for later navigation".
+    """
+    if not config.get("production", False):
+        return html_text
+
+    href_re = re.compile(
+        r'href\s*=\s*(?:"(?P<q1>[^"]*)"|\'(?P<q2>[^\']*)\'|(?P<uq>[^\s>]+))'
+    )
+
+    # Match the opening <a ...> tag only. attrs must not contain a bare '>'
+    # (quoted values are allowed), so the match always stops at the first
+    # unquoted '>', which is exactly the closing '>' of the <a> opening
+    # tag. This is safe because an opening <a> tag cannot legitimately
+    # contain another start tag.
+    tag_re = re.compile(
+        r'<a\s+(?P<attrs>(?:[^>"\']|"[^"]*"|\'[^\']*\')*)>',
+    )
+
+    def _repl(m):
+        attrs = m.group("attrs")
+        # Skip links that already declare a rel attribute
+        if re.search(r'\brel\s*=', attrs, re.IGNORECASE):
+            return m.group(0)
+        hm = href_re.search(attrs)
+        if not hm:
+            return m.group(0)
+        href = hm.group("q1") or hm.group("q2") or hm.group("uq") or ""
+        if not href or href.startswith(("#", "mailto:", "tel:", "javascript:")):
+            return m.group(0)
+        if re.match(r"^[a-zA-Z][a-zA-Z0-9+.-]*:", href):
+            return m.group(0)
+        # Only prefetch same-origin HTML pages (skip assets, anchors, etc.)
+        if not re.search(r"\.(?:html?|htm)$", href, re.IGNORECASE):
+            return m.group(0)
+        # Insert rel="prefetch" right after "<a " so the closing '>' and
+        # any trailing attributes are preserved verbatim.
+        return m.group(0).replace("<a ", '<a rel="prefetch" ', 1)
+
+    return tag_re.sub(_repl, html_text)
+
+
 logger = logging.getLogger(__name__)
 
 

{fr_docs-2.1.6 → fr_docs-2.3.0}/fr_docs/template.py

@@ -18,16 +18,14 @@ TEMPLATE = """\
   <meta name="theme-color" content="#6366f1">
   <meta name="color-scheme" content="dark">
   <link rel="icon" href="{site_prefix}favicon.svg" type="image/svg+xml">
-  <link rel="preconnect" href="https://fonts.googleapis.com">
-  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-  <link href="https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,400..800&family=JetBrains+Mono:wght@400..700&display=swap" rel="stylesheet">
   <link rel="stylesheet" href="{site_prefix}style.css">
+  <link rel="stylesheet" href="{site_prefix}fonts.css" media="print" onload="this.media='all'">
 </head>
 <body>
   <!-- Header -->
   <header class="site-header">
     <button class="menu-toggle" aria-label="Toggle menu">
-      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" width="24" height="24" aria-hidden="true">
         <path d="M3 12h18M3 6h18M3 18h18"/>
       </svg>
     </button>
@@ -65,11 +63,11 @@ TEMPLATE = """\
   </main>
 
   <!-- Back to top -->
-  <button class="back-to-top" aria-label="Back to top">
-    <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5">
-      <path d="M18 15l-6-6-6 6"/>
-    </svg>
-  </button>
+<button class="back-to-top" aria-label="Back to top">
+      <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" aria-hidden="true">
+        <path d="M18 15l-6-6-6 6"/>
+      </svg>
+    </button>
 
     {search_index_inline}
     <script id="code-refs-data" type="application/json">{code_refs_json}</script>
@@ -90,7 +88,7 @@ def build_sidebar_html(current_slug, sidebar_config, ext_sections=None, config=N
         parts.extend(
             [
                 '<div class="search-box">',
-                '  <svg class="search-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/></svg>',
+                '  <svg class="search-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" width="20" height="20" aria-hidden="true"><circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/></svg>',
                 '  <input type="text" id="sidebar-search" placeholder="Search docs…">',
                 "</div>",
             ]
@@ -99,10 +97,19 @@ def build_sidebar_html(current_slug, sidebar_config, ext_sections=None, config=N
     for section_name, pages in sidebar_config:
         key = _section_key(section_name)
         is_ext = section_name in ext_sections
+
+        # Auto-expand the section that contains the current page, and
+        # any section with only one page (so users can see its contents
+        # without clicking). If there's only one section total, expand
+        # it regardless.
+        contains_current = any(slug == current_slug for slug, _ in pages)
+        only_section = len(sidebar_config) == 1
+        collapsed = not (contains_current or only_section or len(pages) <= 1)
+
         parts.extend(
             (
                 '<div class="sidebar-section">',
-                f'  <div class="sidebar-heading collapsed" data-section="{key}">{section_name}</div>',
+                f'  <div class="sidebar-heading{" collapsed" if collapsed else ""}" data-section="{key}">{section_name}</div>',
                 '  <ul class="sidebar-links">',
             )
         )

{fr_docs-2.1.6 → fr_docs-2.3.0}/fr_docs.egg-info/PKG-INFO

@@ -1,7 +1,8 @@
 Metadata-Version: 2.4
 Name: fr-docs
-Version: 2.1.6
+Version: 2.3.0
 Summary: Fast static documentation generator with search, versioning, and zero-config setup
+Author: Omena0
 License: # PolyForm Noncommercial License 1.0.0
         
         <https://polyformproject.org/licenses/noncommercial/1.0.0>
@@ -134,10 +135,91 @@ License: # PolyForm Noncommercial License 1.0.0
         **Use** means anything you do with the software requiring one
         of your licenses.
         
+Project-URL: Homepage, https://omena0.dev/fr-docs/
+Project-URL: Documentation, https://omena0.dev/fr-docs/
+Project-URL: Repository, https://github.com/Omena0/fr-docs
+Project-URL: Issues, https://github.com/Omena0/fr-docs/issues
+Keywords: documentation,documentation-generator,static-site-generator,markdown,github-pages,static-site,docs
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Build Tools
 Requires-Python: >=3.14
+Description-Content-Type: text/markdown
 License-File: LICENSE.md
 Requires-Dist: fastpylight>=0.1.18
 Requires-Dist: markdown
 Requires-Dist: xxhash>=4.0.1
 Requires-Dist: zstandard
 Dynamic: license-file
+
+
+# Fr-docs
+
+Generate fast, fully featured, modern documentation pages from markdown for GitHub pages and static hosting.
+
+[![Lint](https://github.com/Omena0/fr-docs/actions/workflows/lint.yml/badge.svg)](https://github.com/Omena0/fr-docs/actions/workflows/lint.yml)
+[![Docs](https://github.com/Omena0/fr-docs/actions/workflows/pages.yml/badge.svg)](https://github.com/Omena0/fr-docs/actions/workflows/pages.yml)
+[![PyPi](https://github.com/Omena0/fr-docs/actions/workflows/publish.yml/badge.svg)](https://github.com/Omena0/fr-docs/actions/workflows/publish.yml)
+[![CodeQL](https://github.com/Omena0/fr-docs/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/Omena0/fr-docs/actions/workflows/github-code-scanning/codeql)
+
+## Documentation
+
+- [Getting Started](https://omena0.dev/fr-docs/)
+- [Installation](https://omena0.dev/fr-docs/installation)
+- [Quickstart](https://omena0.dev/fr-docs/quickstart)
+- [Configuration](https://omena0.dev/fr-docs/config.json)
+- [Showcase](https://omena0.dev/fr-docs/showcase)
+- [Pagespeed](https://omena0.dev/fr-docs/pagespeed) — performance metrics
+
+## Overview
+
+Fr-docs is a generic, configurable documentation builder for Python projects. It converts Markdown source files into a searchable, optimized static HTML site with zero-config setup.
+
+### Key Features
+
+- **Config-driven**: All settings defined in `config.json`
+  - Project name, URL, description, and sidebar structure
+  - Search, code references, auto-linking, and related pages
+  - Build options: workers, minification, zstd level, and HTML optimization
+
+- **Zero-config setup**: Works out of the box with sensible defaults
+- **Search**: Full-text search with Zstandard-compressed index
+  - Symbol-level search across all source files
+  - File index for browsing source code
+  - Per-file source highlights with caching
+
+- **Optimized**: HTML minification, critical CSS/JS inlining, Zstd compression
+  - Critical CSS extracted and inlined for both mobile and desktop viewports
+  - JavaScript and CSS minified with `terser` and `html-minifier-next`
+  - Zstd-compressed search index, source files, highlights, and metadata
+  - Adaptive zstd level selection (scans 1..configured, picks the smallest)
+
+- **Multi-environment**: Different configs for production, staging, development
+- **Parallel builds**: Threaded page generation for faster builds
+- **Git integration**: Automatic metadata extraction from git commits
+  - Version options derived from commit messages (e.g. `4D - fix bug` → `4.4.0`)
+  - Commit SHA and message embedded in the version selector
+
+- **Local font serving**: Fonts downloaded at build time and served from the site's own origin
+  - No third-party font round-trips or 404s when Google changes the URL scheme
+  - `font-display: swap` with metric-compatible `font-ascent-descent` fallbacks
+  - Primary body font weight preloaded for faster first paint
+
+- **Sidebar**: Collapsible sections with auto-expansion
+  - The section containing the current page is expanded on load
+  - Single-page sections and single-section sites are expanded by default
+
+- **Inline copy commands**: Prefix inline code with `c` to create copy-on-click links
+- **Code references**: Auto-link bare filename references to their source files
+- **Backlinks and related pages**: Automatically generated navigation between related content
+
+### Projects that use fr-docs
+
+- [Fr-docs](https://omena0.dev/fr-docs/)
+- [PyJavaBridge](https://omena0.dev/PyJavaBridge)

fr_docs-2.3.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = [
+    "setuptools>=68.0",
+]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fr-docs"
+version = "2.3.0"
+description = "Fast static documentation generator with search, versioning, and zero-config setup"
+readme = "README.md"
+requires-python = ">=3.14"
+authors = [
+    { name = "Omena0" },
+]
+keywords = [
+    "documentation",
+    "documentation-generator",
+    "static-site-generator",
+    "markdown",
+    "github-pages",
+    "static-site",
+    "docs",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Documentation",
+    "Topic :: Software Development :: Documentation",
+    "Topic :: Software Development :: Build Tools",
+]
+dependencies = [
+    "fastpylight>=0.1.18",
+    "markdown",
+    "xxhash>=4.0.1",
+    "zstandard",
+]
+
+[project.license]
+file = "LICENSE.md"
+
+[project.urls]
+Homepage = "https://omena0.dev/fr-docs/"
+Documentation = "https://omena0.dev/fr-docs/"
+Repository = "https://github.com/Omena0/fr-docs"
+Issues = "https://github.com/Omena0/fr-docs/issues"
+
+[project.scripts]
+fr-docs = "fr_docs.build:main"
+
+[tool.setuptools.packages.find]
+include = [
+    "fr_docs*",
+]

fr_docs-2.1.6/pyproject.toml

@@ -1,28 +0,0 @@
-[build-system]
-requires = [
-    "setuptools>=68.0",
-]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "fr-docs"
-version = "2.1.6"
-description = "Fast static documentation generator with search, versioning, and zero-config setup"
-requires-python = ">=3.14"
-dependencies = [
-    "fastpylight>=0.1.18",
-    "markdown",
-    "xxhash>=4.0.1",
-    "zstandard",
-]
-
-[project.license]
-file = "LICENSE.md"
-
-[project.scripts]
-fr-docs = "fr_docs.build:main"
-
-[tool.setuptools.packages.find]
-include = [
-    "fr_docs*",
-]