mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2026-11-09 20:26:33 +00:00
kevinveenbirkenbachandClaude Opus 5
bd15eae9fa
The gettext build emitted 23251 warnings. Three causes carried 22424 of them, and each is answered with the mechanism sphinx supplies. conf.py read .yml and .yaml through the reStructuredText parser, where yaml indentation is a block quote: 16107 warnings, and the pages had no title either. A parser renders them as the literal block they are, and marks them orphan because a yaml file is reference material rather than a chapter, which drops another 3062 toctree warnings. myst builds a document reference only when the link target is_file(), so every link to a directory fell through as unresolvable. A post-transform ahead of myst's resolver points such a link at the directory's README, but only where that README exists, which leaves the genuinely dangling ones reported. Together with myst_heading_anchors, which was never configured, that clears 2921 missing cross-references and 320 python references. Measured per step over four full builds: 23251 -> 7130 -> 4068 -> 827. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
54 lines
1.8 KiB
Python
54 lines
1.8 KiB
Python
"""Render a YAML source file as the literal block it is.
|
|
|
|
Sphinx read ``.yml`` and ``.yaml`` through the reStructuredText parser, where
|
|
YAML indentation reads as a block quote: 9650 of the build's ``Unexpected
|
|
indentation`` errors came from that one mapping, and the pages carried no title
|
|
either, because a YAML file has no heading to find.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from pathlib import Path
|
|
|
|
from docutils import nodes
|
|
from sphinx.parsers import Parser
|
|
|
|
|
|
def _orphan() -> nodes.docinfo:
|
|
"""Return the docinfo Sphinx reads the ``orphan`` metadata flag from."""
|
|
field = nodes.field()
|
|
field += nodes.field_name(text="orphan")
|
|
field += nodes.field_body()
|
|
info = nodes.docinfo()
|
|
info += field
|
|
return info
|
|
|
|
|
|
class YamlParser(Parser):
|
|
"""Parse a YAML file into a page titled after it, holding its source."""
|
|
|
|
supported = ("yaml",)
|
|
|
|
def parse(self, inputstring: str, document: nodes.document) -> None:
|
|
"""Fill ``document`` with the source of the YAML file it was read from.
|
|
|
|
The page is marked ``orphan``: a YAML file is reference material reached
|
|
from a link in prose, not a chapter of the manual, and every one of them
|
|
would otherwise report itself missing from the toctree.
|
|
|
|
Args:
|
|
inputstring: the file's content.
|
|
document: the docutils document to populate.
|
|
"""
|
|
title = Path(str(document["source"])).name
|
|
document += _orphan()
|
|
section = nodes.section(ids=[nodes.make_id(title)], names=[title])
|
|
section += nodes.title(text=title)
|
|
section += nodes.literal_block(inputstring, inputstring, language="yaml")
|
|
document += section
|
|
|
|
|
|
def setup(app):
|
|
app.add_source_parser(YamlParser)
|
|
return {"version": "1.0", "parallel_read_safe": True}
|