rootiest
16e969ee15
docs/manual/** plus the Astro Starlight site (https://fish-config-docs.pages.dev/) replace the Gitea wiki (docs/wiki/) and chunked offline HTML (docs/html/, docs/html-style.html) as the published documentation surface. Retires the now-unused docs/split-wiki.py and docs/split-manual.py generators alongside them. - config-help --html now opens the published site root instead of resolving a local sitemap anchor; when a keyword was given it prints a note that deep links aren't available yet and to use the site's search box. - open-url and docs/manual/05-functions/14-miscellaneous.md examples repointed from docs/html/index.html to the site URL. - docs/manual/11-viewing-this-manual.md rewritten to document the four access paths: the website, the man page, in-terminal pager, and reading docs/manual/** directly. fish-config.index updated to match the new headings. - README.md documentation section and Zoxide attribution link repointed at the site; corrected the stale "single source file" claim about fish-config.md. - Regenerated docs/fish-config.md via build-manual.py --concat.
87 lines
2.8 KiB
Python
87 lines
2.8 KiB
Python
#!/usr/bin/env python3
|
|
# Copyright (C) 2026 Rootiest
|
|
# SPDX-License-Identifier: AGPL-3.0-or-later
|
|
"""Shared helpers for the docs/manual SSOT pipeline.
|
|
|
|
Frontmatter parsing, deterministic tree ordering, and heading level shifts.
|
|
Used by build-manual.py and verify-manual.py.
|
|
"""
|
|
|
|
import re
|
|
from pathlib import Path
|
|
|
|
import yaml
|
|
|
|
FENCE_RE = re.compile(r"^\s*(```|~~~)")
|
|
HEADING_RE = re.compile(r"^(#{1,6})(\s)")
|
|
|
|
|
|
def parse(path: Path) -> tuple[dict, str]:
|
|
"""Split a markdown file into (frontmatter dict, body text).
|
|
|
|
Files without a leading `---` block yield an empty dict and the whole
|
|
text as body. Body is returned with trailing whitespace stripped.
|
|
"""
|
|
text = path.read_text()
|
|
if not text.startswith("---\n"):
|
|
return {}, text.rstrip()
|
|
end = text.find("\n---\n", 4)
|
|
if end == -1:
|
|
return {}, text.rstrip()
|
|
fm = yaml.safe_load(text[4:end]) or {}
|
|
return fm, text[end + 5 :].removeprefix("\n").rstrip()
|
|
|
|
|
|
def serialize(fm: dict, body: str) -> str:
|
|
"""Render a frontmatter dict and body back into markdown text."""
|
|
block = yaml.safe_dump(fm, sort_keys=False, allow_unicode=True).rstrip()
|
|
return f"---\n{block}\n---\n\n{body.rstrip()}\n"
|
|
|
|
|
|
def shift_headings(body: str, by: int) -> str:
|
|
"""Add `by` levels to every ATX heading, ignoring fenced code blocks.
|
|
|
|
Negative values promote headings. Level is clamped to [1, 6].
|
|
"""
|
|
if by == 0:
|
|
return body
|
|
out, in_fence = [], False
|
|
for line in body.split("\n"):
|
|
if FENCE_RE.match(line):
|
|
in_fence = not in_fence
|
|
if not in_fence:
|
|
line = HEADING_RE.sub(
|
|
lambda m: "#" * max(1, min(6, len(m.group(1)) + by)) + m.group(2), line
|
|
)
|
|
out.append(line)
|
|
return "\n".join(out)
|
|
|
|
|
|
def _sort_key(entry: Path) -> tuple:
|
|
"""Order by sidebar.order when present, else by filename. Stable."""
|
|
target = entry / "index.md" if entry.is_dir() else entry
|
|
order = None
|
|
if target.exists():
|
|
fm, _ = parse(target)
|
|
order = (fm.get("sidebar") or {}).get("order")
|
|
return (order is None, order if order is not None else 0, entry.name)
|
|
|
|
|
|
def walk(root: Path, depth: int = 0) -> list[tuple[Path, int]]:
|
|
"""Return ordered (path, depth) pairs for every markdown file under root.
|
|
|
|
A directory sorts at the position of its index.md and its children are
|
|
emitted immediately afterwards at depth+1.
|
|
"""
|
|
entries = [e for e in root.iterdir() if e.is_dir() or e.suffix == ".md"]
|
|
result: list[tuple[Path, int]] = []
|
|
for entry in sorted(entries, key=_sort_key):
|
|
if entry.is_dir():
|
|
index = entry / "index.md"
|
|
if index.exists():
|
|
result.append((index, depth))
|
|
result.extend(walk(entry, depth + 1))
|
|
elif entry.name != "index.md" or depth == 0:
|
|
result.append((entry, depth))
|
|
return result
|