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

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

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

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

@@ -111,4 +111,4 @@ def main() -> None:
 
 
 if __name__ == "__main__":
-    main()
+    main()

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

@@ -626,12 +626,25 @@ def main(argv=None) -> None:
                 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}/"
-                )
+                symlinked = 0
+                for f in sorted(Path(config["_out_dir"]).rglob("*")):
+                    if not f.is_file() or f.name.startswith("."):
+                        continue
+                    # Skip files inside the prefix directory itself
+                    try:
+                        f.relative_to(prefix_dir)
+                        continue
+                    except ValueError:
+                        pass
+                    rel = f.relative_to(config["_out_dir"])
+                    link_path = prefix_dir / rel
+                    link_path.parent.mkdir(parents=True, exist_ok=True)
+                    if link_path.is_symlink() or link_path.exists():
+                        with contextlib.suppress(OSError):
+                            link_path.unlink()
+                    link_path.symlink_to(f.resolve())
+                    symlinked += 1
+                print(f"   ✓ Symlinked {symlinked} files into {prefix}/")
             except OSError as e:
                 print(f"   ✗ Failed to create {prefix}/ symlinks: {e}")
 
@@ -646,6 +659,3 @@ def get_all_slugs(config):
 
     return slugs
 
-
-if __name__ == "__main__":
-    main()

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

@@ -38,7 +38,13 @@ def _parse_commit_log(log_out):
 
 
 def _build_pages_by_commit(out, slugs):
-    """Build pages_by_commit mapping from git log output."""
+    """Build pages_by_commit mapping from git log output.
+
+    Each slug in ``slugs`` is a normalized slug like ``core/entity``. The
+    git log ``--name-only`` output lists file paths like
+    ``docs/src/core/entity.md``; we strip the configured source prefix
+    and ``.md`` suffix to recover the slug.
+    """
     pages_by_commit = {}
     current_commit = None
     for line in out.splitlines():
@@ -49,9 +55,26 @@ def _build_pages_by_commit(out, slugs):
         if re.fullmatch(r"[0-9a-f]{7,40}", line):
             current_commit = line
         elif current_commit:
-            slug = Path(line).stem
-            if slug in slugs:
-                pages_by_commit.setdefault(current_commit, []).append(slug)
+            # Recover the slug from the file path: strip dir prefix and .md
+            slug = line
+            if slug.endswith(".md"):
+                slug = slug[:-3]
+            # Try to match against known slugs (handles prefix variations)
+            matched = None
+            for s in slugs:
+                src_path = s + ".md"
+                if line.endswith(src_path) or line.endswith(f"/{src_path}") or line == src_path:
+                    matched = s
+                    break
+            if matched is None:
+                # Fall back to basename matching for flat layouts
+                base = Path(line).stem
+                for s in slugs:
+                    if s.rsplit("/", 1)[-1] == base:
+                        matched = s
+                        break
+            if matched is not None:
+                pages_by_commit.setdefault(current_commit, []).append(matched)
     return pages_by_commit
 
 

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

@@ -35,7 +35,7 @@ from .markdown import (
     rewrite_md_links,
 )
 from .search import search_include_config
-from .slug import slug_output_name
+from .slug import relative_slug_path, slug_output_name
 from .syntax import (
     URL_ATTR_RE,
     format_custom_tags,
@@ -282,7 +282,7 @@ def _render_backlinks_and_related(body_md, body_html, slug, config, search_index
         and page_data.get("backlinks")
         and not no_backlinks
     ):
-        backlinks_html = _render_backlinks(page_data["backlinks"], search_index)
+        backlinks_html = _render_backlinks(page_data["backlinks"], search_index, slug)
         if has_backlinks_tag:
             body_html = body_html.replace("<p><backlinks></p>", backlinks_html)
             body_html = body_html.replace("<p><backlinks></p>\n", backlinks_html)
@@ -293,7 +293,7 @@ def _render_backlinks_and_related(body_md, body_html, slug, config, search_index
         and page_data.get("related")
         and not no_related
     ):
-        related_html = _render_related(page_data["related"], search_index)
+        related_html = _render_related(page_data["related"], search_index, slug)
         if has_related_tag:
             body_html = body_html.replace("<p><related></p>", related_html)
             body_html = body_html.replace("<p><related></p>\n", related_html)
@@ -332,7 +332,7 @@ def build_page(slug, config, slug_page_keys) -> None:
     body_html = rewrite_md_links(body_html, slug, slug_page_keys)
 
     if feature_enabled(config, "auto_link"):
-        body_html = auto_link_filenames(body_html, config.get("_slug_page_keys", {}))
+        body_html = auto_link_filenames(body_html, config.get("_slug_page_keys", {}), slug)
 
     code_refs = []
     if feature_enabled(config, "code_references"):
@@ -378,6 +378,7 @@ def build_page(slug, config, slug_page_keys) -> None:
 
     out_name = slug_output_name(slug, config)
     out_path = Path(config["_out_dir"], out_name)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
     out_path.write_text(out_html, encoding="utf-8")
 
 
@@ -389,9 +390,11 @@ def _strip_site_prefix(out_dir, stripped_prefix, backed_up):
     prefix_pat = re.compile(
         rf'href=(["\']?){re.escape(stripped_prefix)}/([^"\'\s>]+)\1'
     )
-    for html_file in out_dir.glob("*.html"):
+    for html_file in out_dir.rglob("*.html"):
+        if html_file.name.startswith("."):
+            continue
         raw = html_file.read_text(encoding="utf-8")
-        backup = out_dir / f".critical_orig_{html_file.stem}.html"
+        backup = html_file.parent / f".critical_orig_{html_file.stem}.html"
         backup.write_text(raw, encoding="utf-8")
         backed_up.append(backup)
         rewritten = prefix_pat.sub(
@@ -436,7 +439,8 @@ def _run_critical_on_file(html_file, out_dir):
 def _restore_backups(out_dir, backed_up):
     """Restore original HTML for pages critical didn't inline, and clean up backups."""
     for backup in backed_up:
-        target = out_dir / f"{backup.stem.replace('.critical_orig_', '')}.html"
+        # Backup is stored alongside the original: <dir>/.critical_orig_<stem>.html
+        target = backup.parent / f"{backup.stem.replace('.critical_orig_', '')}.html"
         if target.exists() and backup.exists():
             target_content = target.read_text(encoding="utf-8")
             if "data-critical" not in target_content:
@@ -478,7 +482,9 @@ def optimize_all_pages(config) -> None:
 
     try:
         _strip_site_prefix(out_dir, stripped_prefix, backed_up)
-        for html_file in out_dir.glob("*.html"):
+        for html_file in out_dir.rglob("*.html"):
+            if html_file.name.startswith("."):
+                continue
             _run_critical_on_file(html_file, out_dir)
     finally:
         _restore_backups(out_dir, backed_up)
@@ -495,7 +501,9 @@ def minify_all_pages(config) -> None:
     if not out_dir.is_dir():
         return
 
-    for html_file in sorted(out_dir.glob("*.html")):
+    for html_file in sorted(out_dir.rglob("*.html")):
+        if html_file.name.startswith("."):
+            continue
         try:
             raw = html_file.read_text(encoding="utf-8")
             minified = minify_html(raw, config)
@@ -555,7 +563,7 @@ def add_internal_prefetch_links(html_text, config):
 logger = logging.getLogger(__name__)
 
 
-def _render_backlinks(backlinks, search_index) -> str:
+def _render_backlinks(backlinks, search_index, current_slug=""):
     """Render backlinks HTML."""
     if not backlinks:
         return ""
@@ -564,9 +572,9 @@ def _render_backlinks(backlinks, search_index) -> str:
         if page := next((p for p in search_index if p.get("slug") == bl_slug), None):
             url = page.get("url", f"{bl_slug}.html")
             title = page.get("title", bl_slug)
+            if not url.startswith("http"):
+                url = relative_slug_path(current_slug, bl_slug)
             items.append(f'<li><a href="{url}">{title}</a></li>')
-    if not items:
-        return ""
     return (
         f"<h2>Backlinks</h2>"
         f'<details class="backlinks-details">'
@@ -580,7 +588,7 @@ def _render_backlinks(backlinks, search_index) -> str:
     )
 
 
-def _render_related(related, search_index) -> str:
+def _render_related(related, search_index, current_slug=""):
     """Render related pages HTML."""
     if not related:
         return ""
@@ -589,6 +597,8 @@ def _render_related(related, search_index) -> str:
         if page := next((p for p in search_index if p.get("slug") == rel_slug), None):
             url = page.get("url", f"{rel_slug}.html")
             title = page.get("title", rel_slug)
+            if not url.startswith("http"):
+                url = relative_slug_path(current_slug, rel_slug)
             items.append(f'<li><a href="{url}">{title}</a></li>')
 
     if not items:

{fr_docs-2.5.0 → fr_docs-3.1.0}/fr_docs/markdown.py

@@ -12,6 +12,7 @@ from markdown.extensions.tables import TableExtension
 
 from .slug import (
     normalize_slug,
+    relative_slug_path,
     slug_output_name,
 )
 from .syntax import URL_ATTR_RE
@@ -91,7 +92,12 @@ def convert_markdown(text):
 
 
 def resolve_md_target(md_target, current_slug, slug_page_keys):
-    """Resolve a markdown link target to an output HTML filename."""
+    """Resolve a markdown link target to a page-relative output HTML filename.
+
+    Returns a path relative to the current page (e.g. ``../index.html`` from
+    ``core/entity.html`` to ``index.html``) so links work at any depth in the
+    directory tree.
+    """
     raw = str(md_target or "").strip()
     if not raw:
         return raw
@@ -116,9 +122,9 @@ def resolve_md_target(md_target, current_slug, slug_page_keys):
 
     for candidate in candidates:
         if candidate in slug_page_keys:
-            return slug_output_name(candidate)
+            return relative_slug_path(current_slug, candidate)
 
-    return slug_output_name(normalize_slug(raw))
+    return relative_slug_path(current_slug, normalize_slug(raw))
 
 
 def rewrite_md_links(html_text, current_slug, slug_page_keys):
@@ -139,7 +145,7 @@ def rewrite_md_links(html_text, current_slug, slug_page_keys):
     )
 
 
-def auto_link_filenames(html_text, slug_page_keys):
+def auto_link_filenames(html_text, slug_page_keys, current_slug=""):
     """Auto-link bare filename references like `config.json` to their .md pages.
 
     Only processes filenames INSIDE inline code tags (<code>...</code>).
@@ -148,12 +154,12 @@ def auto_link_filenames(html_text, slug_page_keys):
     if not slug_page_keys:
         return html_text
 
-    # Build a map of filename (without .md) -> output HTML file
+    # Build a map of filename (without .md) -> page-relative output HTML file
     filename_map = {}
     for slug in slug_page_keys:
         filename = slug.rsplit("/", 1)[-1]
         if filename:
-            output = slug_output_name(slug)
+            output = relative_slug_path(current_slug, slug)
             filename_map[filename.lower()] = output
             filename_map[f"{filename}.md".lower()] = output
 

{fr_docs-2.5.0 → fr_docs-3.1.0}/fr_docs/search.py

@@ -5,7 +5,7 @@ from pathlib import Path
 
 from .config_accessors import feature_enabled
 from .frontmatter import parse_frontmatter
-from .slug import normalize_slug, slug_output_name, slug_page_key
+from .slug import normalize_slug, relative_slug_path, slug_output_name
 from .utils import output_href
 
 # Symbol extraction patterns for various languages
@@ -536,7 +536,7 @@ def build_search_index(slugs, config):
             title = meta.get("title", slug.capitalize())
             sections = _parse_search_sections(body_md)
 
-            page_key = slug_page_key(slug, config)
+            page_key = normalize_slug(slug)
             url = output_href(slug_output_name(slug, config), config)
             search_index.append(
                 {

fr_docs-3.1.0/fr_docs/slug.py

@@ -0,0 +1,79 @@
+"""Slug normalization and output-key utilities for fr-docs."""
+
+
+def slug_basename(slug):
+    """Extract the filename part from a possibly prefixed slug (e.g. 'core/entity' → 'entity')."""
+    normalized = str(slug).replace("\\", "/").strip("/")
+    return normalized.rsplit("/", 1)[-1] if normalized else ""
+
+
+def normalize_slug(slug):
+    """Normalize slugs to forward-slash format for cross-platform consistency.
+    Also resolves relative path segments like '..' and '.'.
+    """
+    # Convert to forward slashes and strip
+    normalized = str(slug).replace("\\", "/").strip("/")
+    # Resolve relative path segments
+    parts = []
+    for part in normalized.split("/"):
+        if part == "..":
+            if parts:
+                parts.pop()
+        elif part and part != ".":
+            parts.append(part)
+    return "/".join(parts)
+
+
+def build_slug_page_keys(slugs):
+    """Build a mapping of normalized slug → normalized slug (identity mapping).
+
+    With directory-tree output, file name collisions are avoided by
+    preserving the directory structure in the output path, so no
+    disambiguation suffixes are needed.
+    """
+    return {normalize_slug(slug): normalize_slug(slug) for slug in slugs}
+
+
+def slug_page_key(slug, config):
+    """Return the stable output key for a slug (the normalized slug)."""
+    return normalize_slug(slug)
+
+
+def slug_output_name(slug, config=None) -> str:
+    """Return output HTML filename for a slug, preserving directory structure.
+
+    Slugs like 'core/entity' produce 'core/entity.html'. The 'index' slug
+    at the root produces 'index.html'; an 'index' nested under a directory
+    (e.g. 'core/index') produces 'core/index.html'.
+    """
+    if config is None:
+        return f"{slug}.html"
+    return f"{normalize_slug(slug)}.html"
+
+
+def relative_slug_path(from_slug, to_slug):
+    """Compute the page-relative path from ``from_slug`` to ``to_slug``.
+
+    Returns a string like ``../index.html`` or ``core/entity.html`` suitable
+    for use as an ``href`` value in a page at ``from_slug``.
+    """
+    from_name = slug_output_name(from_slug)
+    to_name = slug_output_name(to_slug)
+
+    from_parts = from_name.split("/")
+    to_parts = to_name.split("/")
+
+    # Find common prefix
+    i = 0
+    while i < min(len(from_parts), len(to_parts)) and from_parts[i] == to_parts[i]:
+        i += 1
+
+    # Number of directory levels to go up (from the from_page's directory)
+    # from_parts has the filename as the last element; we need to go up
+    # from the directory containing from_name.
+    up = len(from_parts) - 1 - i
+    # Remaining path to the target
+    down = to_parts[i:]
+
+    parts = [".."] * up + down
+    return "/".join(parts) if parts else to_name

{fr_docs-2.5.0 → fr_docs-3.1.0}/fr_docs/template.py

@@ -3,7 +3,7 @@
 import re
 
 from .config_accessors import feature_enabled
-from .slug import slug_basename, slug_output_name
+from .slug import relative_slug_path
 
 TEMPLATE = """\
 <!DOCTYPE html>
@@ -141,7 +141,7 @@ def build_sidebar_html(current_slug, sidebar_config, tagged_sections=None, confi
         )
         for slug, label in pages:
             active = ' class="active"' if slug == current_slug else ""
-            href = slug_output_name(slug_basename(slug))
+            href = relative_slug_path(current_slug, slug)
             display = label
             parts.append(f'    <li><a href="{href}"{active}>{display}</a></li>')
 

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

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

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

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

fr_docs-2.5.0/fr_docs/slug.py

@@ -1,71 +0,0 @@
-"""Slug normalization and output-key utilities for fr-docs."""
-
-
-def slug_basename(slug):
-    """Extract the filename part from a possibly prefixed slug (e.g. 'core/entity' → 'entity')."""
-    normalized = str(slug).replace("\\", "/").strip("/")
-    return normalized.rsplit("/", 1)[-1] if normalized else ""
-
-
-def normalize_slug(slug):
-    """Normalize slugs to forward-slash format for cross-platform consistency.
-    Also resolves relative path segments like '..' and '.'.
-    """
-    # Convert to forward slashes and strip
-    normalized = str(slug).replace("\\", "/").strip("/")
-    # Resolve relative path segments
-    parts = []
-    for part in normalized.split("/"):
-        if part == "..":
-            if parts:
-                parts.pop()
-        elif part and part != ".":
-            parts.append(part)
-    return "/".join(parts)
-
-
-def build_slug_page_keys(slugs):
-    """Build unique output keys for slugs, disambiguating basename collisions."""
-    groups = {}
-    for slug in slugs:
-        norm = normalize_slug(slug)
-        base = slug_basename(norm).lower()
-        groups.setdefault(base, []).append(norm)
-
-    keys = {}
-    used = set()
-    for base, entries in sorted(groups.items()):
-        entries = sorted(set(entries))
-        has_collision = len(entries) > 1
-        for norm in entries:
-            if not has_collision:
-                base_key = slug_basename(norm)
-            elif base == "index" == norm:
-                base_key = "index"
-            else:
-                base_key = norm.replace("/", "__")
-
-            candidate = base_key
-            suffix = 2
-            while candidate in used:
-                candidate = f"{base_key}-{suffix}"
-                suffix += 1
-
-            used.add(candidate)
-            keys[norm] = candidate
-
-    return keys
-
-
-def slug_page_key(slug, config):
-    """Return the stable output key for a slug."""
-    norm = normalize_slug(slug)
-    return config.get("_slug_page_keys", {}).get(norm, slug_basename(norm))
-
-
-def slug_output_name(slug, config=None) -> str:
-    """Return output HTML filename for a slug."""
-    if config is None:
-        return f"{slug}.html"
-    key = slug_page_key(slug, config)
-    return "index.html" if key == "index" else f"{key}.html"