Source code for rigconductor.manual
# ╔══════════════════════════════════════════════════════════════════╗
# ║ Rig Conductor — manual ║
# ║ « one Markdown file, read in the app and printed to PDF » ║
# ╠══════════════════════════════════════════════════════════════════╣
# ║ Locates the user manual (docs/manual/user_manual.md) and parses ║
# ║ its headings into sections, so the in-app Help window, F1 on ║
# ║ every wizard page and the PDF share one source of truth. ║
# ╚══════════════════════════════════════════════════════════════════╝
"""User-manual helpers that need no Qt.
The manual is written in the Markdown that Qt's ``QTextDocument.setMarkdown``
understands (CommonMark and GitHub tables): no admonitions, attribute lists
or tabs. Slugs follow Python-Markdown's ``toc`` so ``#links`` also work on a
docs site.
"""
from __future__ import annotations
import re
import unicodedata
from dataclasses import dataclass
from pathlib import Path
REPO_ROOT = Path(__file__).resolve().parents[2]
MANUAL_DIR = REPO_ROOT / "docs" / "manual"
MANUAL_PATH = MANUAL_DIR / "user_manual.md"
_HEADING = re.compile(r"^(#{1,6})\s+(.+?)\s*#*\s*$")
_FENCE = re.compile(r"^\s*(```|~~~)")
_LINK = re.compile(r"(!?)\[[^\]]*\]\(([^)\s]+)(?:\s+\"[^\"]*\")?\)")
[docs]
@dataclass(frozen=True)
class Section:
level: int
title: str
slug: str
line: int # 1-based line in the source
[docs]
def load_manual(path: Path = MANUAL_PATH) -> str:
"""The manual's Markdown source."""
return path.read_text(encoding="utf-8")
[docs]
def slugify(title: str) -> str:
"""Python-Markdown's default ``toc`` slug."""
text = re.sub(r"[*_`]", "", title)
text = unicodedata.normalize("NFKD", text).encode("ascii", "ignore").decode("ascii")
text = re.sub(r"[^\w\s-]", "", text).strip().lower()
return re.sub(r"[-\s]+", "-", text)
[docs]
def parse_sections(markdown: str) -> list[Section]:
"""ATX headings in document order, skipping fenced code blocks."""
sections: list[Section] = []
in_fence = False
for number, line in enumerate(markdown.splitlines(), start=1):
if _FENCE.match(line):
in_fence = not in_fence
continue
m = None if in_fence else _HEADING.match(line)
if m:
sections.append(Section(len(m.group(1)), m.group(2), slugify(m.group(2)), number))
return sections
[docs]
def image_targets(markdown: str) -> list[str]:
"""Relative paths of every ```` picture."""
return [target for bang, target in _LINK.findall(markdown) if bang]
[docs]
def anchor_targets(markdown: str) -> list[str]:
"""Slugs of every in-page ``[text](#slug)`` link."""
return [t[1:] for bang, t in _LINK.findall(markdown) if not bang and t.startswith("#")]