docs(site): add inline code spans to generated Starlight pages
Function doc-headers are authored as plain text -- `config-help`, `funcsave` and anyone opening the `.fish` file read them as-is -- so they carry no backticks. The site inherited that and rendered `-a/--all` and `__fish_config_op_aliases` as ordinary prose. docs/codespans.py adds the spans at render time, as the last step of prettify(), so only the site sees them; build_concat() (man page, config-help) is byte-for-byte unchanged. Recognised shapes: flags and flag pairs, `$vars`, SCREAMING_SNAKE env vars, snake_case identifiers, paths and filenames, key chords, command shadow chains (`ls->eza`), runs of tool names, whole command lines in a table column of command lines, and known command names -- drawn from the `_fdc_*` catalog in functions/_fish_deps_catalog.fish, the functions/ listing, and a standard-command list, minus the names that also read as English. Fenced blocks, existing code spans, headings, link targets, URLs, component markup and <FileTree> bodies are passed through untouched, and every rule bails out rather than guess.
This commit is contained in:
+13
-2
@@ -8,12 +8,14 @@
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import functools
|
||||
import json
|
||||
import re
|
||||
import shutil
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
import codespans
|
||||
import manualtools as mt
|
||||
import generate_component_registry
|
||||
|
||||
@@ -484,12 +486,21 @@ def _as_aside(para: list[str]) -> str | None:
|
||||
return f"<Aside {attrs}>\n{body}\n</Aside>"
|
||||
|
||||
|
||||
@functools.lru_cache(maxsize=1)
|
||||
def _code_vocabulary() -> codespans.Vocabulary:
|
||||
"""The command names codespans may wrap, read from the repo once."""
|
||||
return codespans.vocabulary(DOCS.parent)
|
||||
|
||||
|
||||
def prettify(body: str, entry_name: str | None = None) -> str:
|
||||
"""Rewrite a body's indented code blocks and labeled asides for the website.
|
||||
|
||||
Site-only: the man page and `config-help` keep reading the untouched
|
||||
SSOT, where the indented form and the `LABEL:` text are exactly what
|
||||
pandoc/`config-help` want.
|
||||
pandoc/`config-help` want. The same applies to the inline code spans
|
||||
added last: `-a/--all` and `__fish_config_op_aliases` are authored bare
|
||||
so the `functions/*.fish` headers stay readable as plain text, and the
|
||||
backticks the site wants are put on here rather than in the SSOT.
|
||||
"""
|
||||
out: list[str] = []
|
||||
block: list[str] = []
|
||||
@@ -528,7 +539,7 @@ def prettify(body: str, entry_name: str | None = None) -> str:
|
||||
while block and not block[-1].strip():
|
||||
block.pop()
|
||||
out.append(_prettify_block(block, entry_name))
|
||||
return "\n".join(out)
|
||||
return codespans.add_code_spans("\n".join(out), _code_vocabulary())
|
||||
|
||||
|
||||
ENTRY_HEADS = {
|
||||
|
||||
Reference in New Issue
Block a user