Refactor documentation for kmer indexing and phylogenetic models
This commit updates documentation across the board, introducing definitions for kmer constraints, super-kmers, k-mer set distances, SNP models, and sampling design principles. It also clarifies the index construction pipeline and the underlying mathematical models used for genome pair calibration.
This commit is contained in:
1 parent
9da0876ee6
commit
e715528d34
19 files changed
+582
-712
No files matched your search
@@ -1,528 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Convert the MkDocs user documentation (UserDocMD/) into a Gitea/Forgejo wiki tree.
|
||||
|
||||
Gitea/Forgejo wikis use a different link syntax than MkDocs and cannot render
|
||||
multi-line `$$...$$` display math (a known Goldmark/KaTeX limitation: the
|
||||
parser only recognizes the delimiters when the whole block sits on one
|
||||
physical line). This script rewrites the three constructs that would
|
||||
otherwise break, flattens the tree onto page basenames, and copies everything
|
||||
else verbatim:
|
||||
|
||||
* Markdown links [text](path.md) -> [text](PageName)
|
||||
Relative paths (including MkDocs root-relative `/path.md` links) are
|
||||
resolved against the source tree and then flattened to a wiki page id;
|
||||
only the target is rewritten, the label is left untouched. Gitea/Forgejo's
|
||||
own `[[page|label]]` shortlink syntax is deliberately not used: it is
|
||||
post-processed on rendered HTML text nodes, so it cannot match when the
|
||||
label contains inline formatting (a `` `code` `` span splits the text
|
||||
into separate DOM nodes around it) — confirmed empirically on the target
|
||||
instance, where such labels never became links at all, and even a plain
|
||||
label put target and display text in the position swapped from what the
|
||||
MediaWiki-style `[[target|label]]` convention would suggest. A native
|
||||
Markdown link is a real AST link node, so it has neither problem.
|
||||
External links (http(s)://, mailto:) and links pointing outside the
|
||||
source tree are left untouched.
|
||||
* Pandoc citations [@key; @key] -> formatted, CSL-styled citation
|
||||
Gitea/Forgejo's Goldmark does not support the [@key] citation syntax, and
|
||||
a bare `(@key)` fallback is meaningless to a reader without the .bib file
|
||||
open. Files containing citations are instead piped through `pandoc
|
||||
--citeproc` with the project's own `references.bib` and `ecology-letters
|
||||
.csl` — the same files `mkdocs-bibtex` uses for the real site — so the
|
||||
wiki gets the identical citation style, e.g. `[@Zheng2020-ji]` becomes
|
||||
`(Zheng et al. 2020)`, with a formatted bibliography (one `<div id="ref-
|
||||
KEY">` per entry, real title/journal/DOI) appended to that page. This
|
||||
duplicates entries across pages that cite the same source rather than
|
||||
centralizing them on one wiki page — an acceptable tradeoff for a
|
||||
handful of references, and far simpler than inventing a cross-page
|
||||
anchor scheme. Files with no `[@key]` at all skip pandoc entirely.
|
||||
* Multi-line display math $$\\n...\\n$$ -> single-line $$...$$
|
||||
Collapsed onto one line (interior newlines replaced by spaces; `\\\\`
|
||||
row separators are preserved) so Gitea/Forgejo's renderer recognizes it.
|
||||
Inline `$...$` and already single-line `$$...$$` need no change and pass
|
||||
through as-is.
|
||||
|
||||
None of these rewrites touch fenced code blocks (```` ``` ```` or `~~~`,
|
||||
including openings longer than three characters, e.g. ```` ```` ```` wrapping
|
||||
a literal triple-backtick example).
|
||||
|
||||
Wiki page ids are flat (no directories), so a source file living in a
|
||||
sub-directory gets its directory path folded into the page id: a file at
|
||||
`theory/encoding.md` becomes the page `theory-encoding`. Files at the root keep
|
||||
their bare stem, except `index.md` which maps to `Home` — the page name
|
||||
Gitea/Forgejo treats as the wiki's landing page. The same mapping is used to
|
||||
resolve internal links, so cross-directory references stay consistent. If
|
||||
folding still produces a collision the script refuses to write rather than
|
||||
silently dropping a page.
|
||||
|
||||
The `nav:` section of the MkDocs config is reproduced as a `_Sidebar.md` so the
|
||||
wiki keeps the same top-level grouping (Home / Installation / Theory / Usage /
|
||||
Formats / Architecture). Nav entries are usually `{label: path}` mappings, but
|
||||
a bare `path` entry (no explicit label) is also honored: the label is taken
|
||||
from the target file's first `# ` heading, falling back to a prettified
|
||||
filename. The sidebar is static and shown on every page, which is the only
|
||||
way Gitea/Forgejo expose a structured menu; the file is hidden from the page
|
||||
list because its name starts with `_`.
|
||||
|
||||
Usage:
|
||||
mk_wiki.py OUTPUT [OPTIONS]
|
||||
|
||||
Options:
|
||||
--source DIR Source tree (default: UserDocMD next to this script's parent)
|
||||
--config FILE MkDocs user config (default: <repo>/mkdocs-user.yml)
|
||||
--csl FILE CSL citation style (default: <source>/ecology-letters.csl)
|
||||
--bib FILE BibTeX bibliography (default: <source>/references.bib)
|
||||
--no-sidebar do not generate _Sidebar.md
|
||||
--verbose print every conversion
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import re
|
||||
import subprocess
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
import yaml
|
||||
|
||||
|
||||
class ConversionError(Exception):
|
||||
"""Raised when a source file cannot be converted faithfully."""
|
||||
|
||||
|
||||
def _make_lenient_loader() -> type[yaml.SafeLoader]:
|
||||
"""A SafeLoader that ignores unknown YAML tags instead of erroring.
|
||||
|
||||
The MkDocs config uses `!!python/name:pymdownx.superfences.fence_code_format`
|
||||
on a custom-fence entry; PyYAML cannot resolve that tag without an unsafe
|
||||
loader, but the script only needs the `nav:` section, which is plain YAML.
|
||||
Treating unknown tags as their literal scalar value is enough.
|
||||
"""
|
||||
|
||||
class _LenientLoader(yaml.SafeLoader):
|
||||
pass
|
||||
|
||||
def _unknown_constructor(loader: yaml.Loader, node: yaml.Node): # type: ignore[no-untyped-def]
|
||||
if isinstance(node, yaml.ScalarNode):
|
||||
return loader.construct_scalar(node)
|
||||
if isinstance(node, yaml.SequenceNode):
|
||||
return loader.construct_sequence(node)
|
||||
if isinstance(node, yaml.MappingNode):
|
||||
return loader.construct_mapping(node)
|
||||
return None
|
||||
|
||||
_LenientLoader.add_constructor(None, _unknown_constructor)
|
||||
return _LenientLoader
|
||||
|
||||
|
||||
def find_repo_root(start: Path) -> Path:
|
||||
"""Walk up until we find a directory containing UserDocMD/."""
|
||||
for candidate in [start.resolve(), *start.resolve().parents]:
|
||||
if (candidate / "UserDocMD").is_dir():
|
||||
return candidate
|
||||
return start.resolve()
|
||||
|
||||
|
||||
def is_external(target: str) -> bool:
|
||||
return bool(re.match(r"^[a-zA-Z][a-zA-Z0-9+.-]*://", target)) or target.startswith("mailto:")
|
||||
|
||||
|
||||
def split_anchor(target: str) -> tuple[str, str]:
|
||||
if "#" in target:
|
||||
path, anchor = target.split("#", 1)
|
||||
return path, "#" + anchor
|
||||
return target, ""
|
||||
|
||||
|
||||
def wiki_page_id(src_root: Path, abs_target: Path) -> str:
|
||||
"""Map a source file to its wiki page id.
|
||||
|
||||
Wikis are flat, so the directory path is folded into the id: a file at
|
||||
`theory/encoding.md` becomes `theory-encoding`, while a root file keeps its
|
||||
bare stem, except `index.md` which maps to `Home` — the page name
|
||||
Gitea/Forgejo renders as the wiki's landing page.
|
||||
"""
|
||||
rel = abs_target.relative_to(src_root.resolve())
|
||||
parts = list(rel.parts)
|
||||
if len(parts) > 1:
|
||||
# Drop the .md suffix from the last part, join the rest with '-'.
|
||||
return "-".join([*parts[:-1], parts[-1][:-3]])
|
||||
stem = parts[0][:-3]
|
||||
return "Home" if stem == "index" else stem
|
||||
|
||||
|
||||
def resolve_wiki_path(src_root: Path, src_file: Path, target: str) -> str | None:
|
||||
"""Turn a relative markdown target into a wiki page id.
|
||||
|
||||
Returns None for targets we should leave as plain Markdown links
|
||||
(external URLs, non-markdown files, missing files, or targets outside the
|
||||
source tree).
|
||||
"""
|
||||
path, anchor = split_anchor(target)
|
||||
if is_external(path) or path == "":
|
||||
return None
|
||||
if path.startswith("/"):
|
||||
# MkDocs root-relative link: resolved against the docs root, not the
|
||||
# current file's directory (Path("a") / "/b" would silently discard
|
||||
# "a" and resolve "/b" from the filesystem root, which is wrong here).
|
||||
abs_target = (src_root / path.lstrip("/")).resolve()
|
||||
else:
|
||||
abs_target = (src_file.parent / path).resolve()
|
||||
try:
|
||||
abs_target.relative_to(src_root.resolve())
|
||||
except ValueError:
|
||||
return None
|
||||
if abs_target.suffix != ".md":
|
||||
return None
|
||||
if not abs_target.is_file():
|
||||
return None
|
||||
return wiki_page_id(src_root, abs_target) + anchor
|
||||
|
||||
|
||||
LINK_RE = re.compile(r"\[([^\]]*)\]\(([^)\s]+)\)")
|
||||
FENCE_RE = re.compile(r"^(`{3,}|~{3,})")
|
||||
# Pandoc citation syntax, e.g. [@Zheng2020-ji; @Golan2025-xf] — just used to
|
||||
# detect whether a file has any citation worth running through pandoc at all.
|
||||
HAS_CITATION_RE = re.compile(r"\[@[^\]]+\]")
|
||||
|
||||
# pandoc's markdown writer must be told, relative to its own defaults, to:
|
||||
# -smart leave dashes/quotes as written (no em-dash -> "---")
|
||||
# -fenced_divs emit the bibliography as raw HTML <div> (Goldmark
|
||||
# has no ``:::`` fenced-div extension)
|
||||
# -simple_tables, -multiline_tables, -grid_tables, +pipe_tables
|
||||
# keep GFM pipe-table syntax, the only kind Goldmark
|
||||
# parses, instead of pandoc's space-aligned tables
|
||||
# +fenced_code_blocks (pandoc still emits an indented block for a fence
|
||||
# with no language tag regardless of this extension —
|
||||
# such fences need a language hint in the source)
|
||||
# -header_attributes Goldmark has no `{#id .class}` heading-attribute
|
||||
# syntax; without this the "Bibliography" heading pandoc
|
||||
# adds (see BIBLIOGRAPHY_TITLE below) would render with
|
||||
# a literal `{#bibliography .unnumbered}` after it
|
||||
PANDOC_MARKDOWN_FORMAT = (
|
||||
"markdown-smart-fenced_divs-simple_tables-multiline_tables-grid_tables"
|
||||
"-header_attributes+pipe_tables+fenced_code_blocks"
|
||||
)
|
||||
|
||||
# Title pandoc gives the generated bibliography section (always emitted as a
|
||||
# level-1 `# ` heading, with no option to pick the level) — demoted to `##`
|
||||
# below to match the rest of this doc set's heading hierarchy.
|
||||
BIBLIOGRAPHY_TITLE = "Bibliography"
|
||||
|
||||
|
||||
class FenceState:
|
||||
"""Tracks whether the current line is inside a fenced code block.
|
||||
|
||||
A closing fence must use the same character and be at least as long as
|
||||
the opening one (CommonMark rule) — this is what lets a source file wrap
|
||||
a literal ``` example inside a longer ```` fence.
|
||||
"""
|
||||
|
||||
def __init__(self) -> None:
|
||||
self.marker = ""
|
||||
|
||||
def toggle(self, line: str) -> bool:
|
||||
"""Update state for a fence delimiter line; return True if it is one."""
|
||||
m = FENCE_RE.match(line.rstrip("\n"))
|
||||
if not m:
|
||||
return False
|
||||
run = m.group(1)
|
||||
if not self.marker:
|
||||
self.marker = run
|
||||
elif run[0] == self.marker[0] and len(run) >= len(self.marker):
|
||||
self.marker = ""
|
||||
return True
|
||||
|
||||
@property
|
||||
def active(self) -> bool:
|
||||
return bool(self.marker)
|
||||
|
||||
|
||||
def convert_links(text: str, src_root: Path, src_file: Path, verbose: bool) -> str:
|
||||
out_lines: list[str] = []
|
||||
fence = FenceState()
|
||||
|
||||
for line in text.splitlines(keepends=True):
|
||||
if fence.toggle(line) or fence.active:
|
||||
out_lines.append(line)
|
||||
continue
|
||||
|
||||
def repl(m: re.Match) -> str:
|
||||
label, target = m.group(1), m.group(2)
|
||||
wiki = resolve_wiki_path(src_root, src_file, target)
|
||||
if wiki is None:
|
||||
return m.group(0) # external or non-md: leave as Markdown
|
||||
if verbose:
|
||||
print(f" {src_file.relative_to(src_root)}: [{label}]({target}) -> [{label}]({wiki})")
|
||||
return f"[{label}]({wiki})"
|
||||
|
||||
out_lines.append(LINK_RE.sub(repl, line))
|
||||
|
||||
return "".join(out_lines)
|
||||
|
||||
|
||||
def convert_citations(
|
||||
text: str, src_root: Path, src_file: Path, csl_path: Path, bib_path: Path, verbose: bool
|
||||
) -> str:
|
||||
"""Render Pandoc `[@key; @key]` citations with the project's real CSL style.
|
||||
|
||||
Skips files with no citation entirely, so a missing `--csl`/`--bib` or a
|
||||
missing `pandoc` binary is only an error for files that actually need it.
|
||||
"""
|
||||
if not HAS_CITATION_RE.search(text):
|
||||
return text
|
||||
|
||||
if not csl_path.is_file():
|
||||
raise ConversionError(f"{src_file.relative_to(src_root)}: CSL style not found: {csl_path}")
|
||||
if not bib_path.is_file():
|
||||
raise ConversionError(f"{src_file.relative_to(src_root)}: bibliography not found: {bib_path}")
|
||||
|
||||
try:
|
||||
result = subprocess.run(
|
||||
[
|
||||
"pandoc",
|
||||
"--citeproc",
|
||||
f"--csl={csl_path}",
|
||||
f"--bibliography={bib_path}",
|
||||
"--wrap=none",
|
||||
f"--metadata=link-citations=true",
|
||||
f"--metadata=reference-section-title={BIBLIOGRAPHY_TITLE}",
|
||||
"-f",
|
||||
"markdown-smart",
|
||||
"-t",
|
||||
PANDOC_MARKDOWN_FORMAT,
|
||||
],
|
||||
input=text,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
)
|
||||
except FileNotFoundError:
|
||||
raise ConversionError(
|
||||
f"{src_file.relative_to(src_root)}: 'pandoc' not found on PATH, needed to render citations"
|
||||
) from None
|
||||
|
||||
if result.returncode != 0:
|
||||
raise ConversionError(
|
||||
f"{src_file.relative_to(src_root)}: pandoc failed to render citations:\n{result.stderr}"
|
||||
)
|
||||
|
||||
# pandoc always emits the bibliography title as a level-1 heading; demote
|
||||
# it to `##` to match the rest of this doc set's hierarchy.
|
||||
out = result.stdout.replace(f"\n# {BIBLIOGRAPHY_TITLE}\n", f"\n## {BIBLIOGRAPHY_TITLE}\n")
|
||||
|
||||
if verbose:
|
||||
n = len(HAS_CITATION_RE.findall(text))
|
||||
print(f" {src_file.relative_to(src_root)}: rendered {n} citation group(s) via pandoc/{csl_path.name}")
|
||||
|
||||
return out
|
||||
|
||||
|
||||
def convert_math(text: str, src_root: Path, src_file: Path, verbose: bool) -> str:
|
||||
"""Collapse multi-line `$$...$$` display blocks onto a single line.
|
||||
|
||||
Gitea/Forgejo's math renderer only recognizes `$$...$$` when it sits on
|
||||
one physical line; a block opened and closed on their own bare `$$` line
|
||||
(the natural Pandoc/MkDocs style) renders as literal text otherwise.
|
||||
Interior line breaks are replaced by spaces (insignificant in math mode);
|
||||
`\\\\` row separators inside `aligned`/`cases` environments are untouched.
|
||||
Already single-line `$$...$$` and inline `$...$` need no change.
|
||||
"""
|
||||
lines = text.split("\n")
|
||||
out: list[str] = []
|
||||
fence = FenceState()
|
||||
i = 0
|
||||
n = len(lines)
|
||||
while i < n:
|
||||
line = lines[i]
|
||||
if fence.toggle(line) or fence.active:
|
||||
out.append(line)
|
||||
i += 1
|
||||
continue
|
||||
|
||||
if line.strip() == "$$":
|
||||
body: list[str] = []
|
||||
i += 1
|
||||
closed = False
|
||||
while i < n:
|
||||
if lines[i].strip() == "$$":
|
||||
closed = True
|
||||
i += 1
|
||||
break
|
||||
body.append(lines[i].strip())
|
||||
i += 1
|
||||
if not closed:
|
||||
raise ConversionError(
|
||||
f"{src_file.relative_to(src_root)}: unterminated $$ display math block"
|
||||
)
|
||||
collapsed = "$$" + " ".join(part for part in body if part) + "$$"
|
||||
if verbose:
|
||||
print(f" {src_file.relative_to(src_root)}: collapsed {len(body)}-line $$ block")
|
||||
out.append(collapsed)
|
||||
continue
|
||||
|
||||
out.append(line)
|
||||
i += 1
|
||||
|
||||
return "\n".join(out)
|
||||
|
||||
|
||||
def convert_file(
|
||||
src_root: Path, src_file: Path, csl_path: Path, bib_path: Path, verbose: bool
|
||||
) -> str:
|
||||
text = src_file.read_text(encoding="utf-8")
|
||||
# Citations first, before pandoc has seen any of our own wiki-specific
|
||||
# rewrites: it needs to parse plain, unmodified Markdown.
|
||||
text = convert_citations(text, src_root, src_file, csl_path, bib_path, verbose)
|
||||
text = convert_math(text, src_root, src_file, verbose)
|
||||
text = convert_links(text, src_root, src_file, verbose)
|
||||
return text
|
||||
|
||||
|
||||
def _default_label(src_root: Path, rel_path: str) -> str:
|
||||
"""Derive a nav label for a bare `path.md` entry (no explicit label).
|
||||
|
||||
Mirrors MkDocs' own fallback: use the page's first `# ` heading if it has
|
||||
one, otherwise prettify the filename.
|
||||
"""
|
||||
target = src_root / rel_path
|
||||
if target.is_file():
|
||||
for line in target.read_text(encoding="utf-8").splitlines():
|
||||
if line.startswith("# "):
|
||||
return line[2:].strip()
|
||||
return Path(rel_path).stem.replace("_", " ").replace("-", " ").title()
|
||||
|
||||
|
||||
def build_sidebar(src_root: Path, config_path: Path) -> str | None:
|
||||
"""Render the MkDocs `nav:` section as a Gitea/Forgejo `_Sidebar.md`.
|
||||
|
||||
Returns None if the config is missing or has no usable `nav:` section.
|
||||
Each nav entry is either a bare `path` string or a `{label: path}` pair
|
||||
(or a nested list for a group); the path is mapped through `wiki_page_id`
|
||||
so the sidebar links to the flattened page ids.
|
||||
"""
|
||||
if not config_path.is_file():
|
||||
print(f"warning: config not found, skipping sidebar: {config_path}")
|
||||
return None
|
||||
|
||||
try:
|
||||
with config_path.open(encoding="utf-8") as fh:
|
||||
cfg = yaml.safe_load(fh)
|
||||
except yaml.YAMLError:
|
||||
# The MkDocs config carries `!!python/name:...` tags that SafeLoader
|
||||
# cannot resolve; fall back to a lenient loader that treats unknown
|
||||
# tags as plain scalars so the `nav:` section is still readable.
|
||||
try:
|
||||
with config_path.open(encoding="utf-8") as fh:
|
||||
cfg = yaml.load(fh, Loader=_make_lenient_loader())
|
||||
except yaml.YAMLError as exc2:
|
||||
print(f"warning: could not parse {config_path}: {exc2}")
|
||||
return None
|
||||
|
||||
nav = cfg.get("nav") if isinstance(cfg, dict) else None
|
||||
if not nav:
|
||||
print(f"warning: no `nav:` section in {config_path}, skipping sidebar")
|
||||
return None
|
||||
|
||||
def link_line(depth: int, rel_path: str, label: str) -> str:
|
||||
page = wiki_page_id(src_root, (src_root / rel_path).resolve())
|
||||
return f"{' ' * depth}- [{label}]({page})"
|
||||
|
||||
def render_entry(entry: object, depth: int) -> list[str]:
|
||||
if isinstance(entry, str):
|
||||
return [link_line(depth, entry, _default_label(src_root, entry))]
|
||||
if not isinstance(entry, dict):
|
||||
return []
|
||||
lines: list[str] = []
|
||||
for label, target in entry.items():
|
||||
if isinstance(target, str):
|
||||
lines.append(link_line(depth, target, label))
|
||||
elif isinstance(target, list):
|
||||
# Headings must never be indented: CommonMark treats a line
|
||||
# indented by 4+ spaces as a code block, not an ATX heading,
|
||||
# which a depth-scaled indent would trigger from depth 2 on.
|
||||
lines.append(f"## {label}")
|
||||
lines.extend(render_subtree(target, depth + 1))
|
||||
return lines
|
||||
|
||||
def render_subtree(nodes: list[object], depth: int) -> list[str]:
|
||||
out: list[str] = []
|
||||
for node in nodes:
|
||||
out.extend(render_entry(node, depth))
|
||||
return out
|
||||
|
||||
body = render_subtree(nav, 0)
|
||||
if not body:
|
||||
return None
|
||||
|
||||
return "# Wiki sidebar\n\n" + "\n".join(body) + "\n"
|
||||
|
||||
|
||||
def main() -> int:
|
||||
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
|
||||
ap.add_argument("output", help="destination wiki directory (created if missing)")
|
||||
ap.add_argument("--source", default=None, help="source Markdown tree (default: <repo>/UserDocMD)")
|
||||
ap.add_argument("--config", default=None,
|
||||
help="MkDocs user config (default: <repo>/mkdocs-user.yml)")
|
||||
ap.add_argument("--csl", default=None,
|
||||
help="CSL citation style (default: <source>/ecology-letters.csl)")
|
||||
ap.add_argument("--bib", default=None,
|
||||
help="BibTeX bibliography (default: <source>/references.bib)")
|
||||
ap.add_argument("--no-sidebar", action="store_true", help="do not generate _Sidebar.md")
|
||||
ap.add_argument("--verbose", action="store_true", help="print every conversion")
|
||||
args = ap.parse_args()
|
||||
|
||||
script_dir = Path(__file__).resolve().parent
|
||||
repo_root = find_repo_root(script_dir)
|
||||
src_root = Path(args.source).resolve() if args.source else (repo_root / "UserDocMD")
|
||||
out_root = Path(args.output).resolve()
|
||||
config_path = Path(args.config).resolve() if args.config else (repo_root / "mkdocs-user.yml")
|
||||
csl_path = Path(args.csl).resolve() if args.csl else (src_root / "ecology-letters.csl")
|
||||
bib_path = Path(args.bib).resolve() if args.bib else (src_root / "references.bib")
|
||||
|
||||
if not src_root.is_dir():
|
||||
print(f"error: source tree not found: {src_root}", file=sys.stderr)
|
||||
return 2
|
||||
|
||||
md_files = sorted(p for p in src_root.rglob("*.md") if p.is_file())
|
||||
if not md_files:
|
||||
print(f"error: no Markdown files under {src_root}", file=sys.stderr)
|
||||
return 2
|
||||
|
||||
# A wiki is flat, so the destination filename is the source path folded into
|
||||
# a page id. Detect collisions up front so a silent overwrite does not drop
|
||||
# a page.
|
||||
by_name: dict[str, list[Path]] = {}
|
||||
for src in md_files:
|
||||
by_name.setdefault(wiki_page_id(src_root, src), []).append(src)
|
||||
collisions = {name: paths for name, paths in by_name.items() if len(paths) > 1}
|
||||
if collisions:
|
||||
for name, paths in sorted(collisions.items()):
|
||||
print(f"error: wiki page id collision '{name}':", file=sys.stderr)
|
||||
for p in paths:
|
||||
print(f" {p.relative_to(src_root)}", file=sys.stderr)
|
||||
return 2
|
||||
|
||||
out_root.mkdir(parents=True, exist_ok=True)
|
||||
written = 0
|
||||
for src in md_files:
|
||||
dst = out_root / (wiki_page_id(src_root, src) + ".md")
|
||||
try:
|
||||
content = convert_file(src_root, src, csl_path, bib_path, args.verbose)
|
||||
except ConversionError as exc:
|
||||
print(f"error: {exc}", file=sys.stderr)
|
||||
return 2
|
||||
dst.write_text(content, encoding="utf-8")
|
||||
written += 1
|
||||
|
||||
if not args.no_sidebar:
|
||||
sidebar = build_sidebar(src_root, config_path)
|
||||
if sidebar is not None:
|
||||
(out_root / "_Sidebar.md").write_text(sidebar, encoding="utf-8")
|
||||
written += 1
|
||||
|
||||
print(f"converted {written} Markdown file(s) from {src_root} -> {out_root}")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
Reference in new issue
Block a user