diff options
Diffstat (limited to 'nixpkgs/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manual.py')
| -rw-r--r-- | nixpkgs/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manual.py | 101 |
1 files changed, 9 insertions, 92 deletions
diff --git a/nixpkgs/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manual.py b/nixpkgs/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manual.py index c72a9d53cd18..c277d28ca5e4 100644 --- a/nixpkgs/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manual.py +++ b/nixpkgs/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manual.py @@ -13,9 +13,8 @@ from typing import Any, Callable, cast, ClassVar, Generic, get_args, NamedTuple from markdown_it.token import Token from . import md, options -from .docbook import DocBookRenderer, Heading, make_xml_id from .html import HTMLRenderer, UnresolvedXrefError -from .manual_structure import check_structure, FragmentType, is_include, TocEntry, TocEntryType, XrefTarget +from .manual_structure import check_structure, FragmentType, is_include, make_xml_id, TocEntry, TocEntryType, XrefTarget from .md import Converter, Renderer class BaseConverter(Converter[md.TR], Generic[md.TR]): @@ -200,74 +199,6 @@ class RendererMixin(Renderer): def included_options(self, token: Token, tokens: Sequence[Token], i: int) -> str: raise NotImplementedError() -class ManualDocBookRenderer(RendererMixin, DocBookRenderer): - def __init__(self, toplevel_tag: str, revision: str, manpage_urls: Mapping[str, str]): - super().__init__(toplevel_tag, revision, manpage_urls) - - def _render_book(self, tokens: Sequence[Token]) -> str: - assert tokens[1].children - assert tokens[4].children - if (maybe_id := cast(str, tokens[0].attrs.get('id', ""))): - maybe_id = "xml:id=" + xml.quoteattr(maybe_id) - return (f'<book xmlns="http://docbook.org/ns/docbook"' - f' xmlns:xlink="http://www.w3.org/1999/xlink"' - f' {maybe_id} version="5.0">' - f' <title>{self.renderInline(tokens[1].children)}</title>' - f' <subtitle>{self.renderInline(tokens[4].children)}</subtitle>' - f' {super(DocBookRenderer, self).render(tokens[6:])}' - f'</book>') - - def _heading_tag(self, token: Token, tokens: Sequence[Token], i: int) -> tuple[str, dict[str, str]]: - (tag, attrs) = super()._heading_tag(token, tokens, i) - # render() has already verified that we don't have supernumerary headings and since the - # book tag is handled specially we can leave the check this simple - if token.tag != 'h1': - return (tag, attrs) - return (self._toplevel_tag, attrs | { - 'xmlns': "http://docbook.org/ns/docbook", - 'xmlns:xlink': "http://www.w3.org/1999/xlink", - }) - - def _included_thing(self, tag: str, token: Token, tokens: Sequence[Token], i: int) -> str: - result = [] - # close existing partintro. the generic render doesn't really need this because - # it doesn't have a concept of structure in the way the manual does. - if self._headings and self._headings[-1] == Heading('part', 1): - result.append("</partintro>") - self._headings[-1] = self._headings[-1]._replace(partintro_closed=True) - # must nest properly for structural includes. this requires saving at least - # the headings stack, but creating new renderers is cheap and much easier. - r = ManualDocBookRenderer(tag, self._revision, self._manpage_urls) - for (included, path) in token.meta['included']: - try: - result.append(r.render(included)) - except Exception as e: - raise RuntimeError(f"rendering {path}") from e - return "".join(result) - def included_options(self, token: Token, tokens: Sequence[Token], i: int) -> str: - conv = options.DocBookConverter(self._manpage_urls, self._revision, 'fragment', - token.meta['list-id'], token.meta['id-prefix']) - conv.add_options(token.meta['source']) - return conv.finalize(fragment=True) - - # TODO minimize docbook diffs with existing conversions. remove soon. - def paragraph_open(self, token: Token, tokens: Sequence[Token], i: int) -> str: - return super().paragraph_open(token, tokens, i) + "\n " - def paragraph_close(self, token: Token, tokens: Sequence[Token], i: int) -> str: - return "\n" + super().paragraph_close(token, tokens, i) - def code_block(self, token: Token, tokens: Sequence[Token], i: int) -> str: - return f"<programlisting>\n{xml.escape(token.content)}</programlisting>" - def fence(self, token: Token, tokens: Sequence[Token], i: int) -> str: - info = f" language={xml.quoteattr(token.info)}" if token.info != "" else "" - return f"<programlisting{info}>\n{xml.escape(token.content)}</programlisting>" - -class DocBookConverter(BaseConverter[ManualDocBookRenderer]): - INCLUDE_ARGS_NS = "docbook" - - def __init__(self, manpage_urls: Mapping[str, str], revision: str): - super().__init__() - self._renderer = ManualDocBookRenderer('book', revision, manpage_urls) - class HTMLParameters(NamedTuple): generator: str @@ -457,7 +388,7 @@ class ManualHTMLRenderer(RendererMixin, HTMLRenderer): f' </span>' f'</dt>' ) - # we want to look straight through parts because docbook-xsl does too, but it + # we want to look straight through parts because docbook-xsl did too, but it # also makes for more uesful top-level tocs. next_level = walk_and_emit(child, depth - (0 if child.kind == 'part' else 1)) if next_level: @@ -477,7 +408,7 @@ class ManualHTMLRenderer(RendererMixin, HTMLRenderer): '</div>' ) # we don't want to generate the "Title of Contents" header for sections, - # docbook doesn't and it's only distracting clutter unless it's the main table. + # docbook didn't and it's only distracting clutter unless it's the main table. # we also want to generate tocs only for a top-level section (ie, one that is # not itself contained in another section) print_title = toc.kind != 'section' @@ -506,12 +437,12 @@ class ManualHTMLRenderer(RendererMixin, HTMLRenderer): ]) def _make_hN(self, level: int) -> tuple[str, str]: - # for some reason chapters don't increase the hN nesting count in docbook xslts. duplicate - # this for consistency. + # for some reason chapters didn't increase the hN nesting count in docbook xslts. + # originally this was duplicated here for consistency with docbook rendering, but + # it could be reevaluated and changed now that docbook is gone. if self._toplevel_tag == 'chapter': level -= 1 - # TODO docbook compat. these are never useful for us, but not having them breaks manual - # compare workflows while docbook is still allowed. + # this style setting is also for docbook compatibility only and could well go away. style = "" if level + self._hlevel_offset < 3 \ and (self._toplevel_tag == 'section' or (self._toplevel_tag == 'chapter' and level > 0)): @@ -537,7 +468,7 @@ class ManualHTMLRenderer(RendererMixin, HTMLRenderer): if into: toc = TocEntry.of(fragments[0][0][0]) inner.append(self._file_header(toc)) - # we do not set _hlevel_offset=0 because docbook doesn't either. + # we do not set _hlevel_offset=0 because docbook didn't either. else: inner = outer in_dir = self._in_dir @@ -742,12 +673,6 @@ class HTMLConverter(BaseConverter[ManualHTMLRenderer]): -def _build_cli_db(p: argparse.ArgumentParser) -> None: - p.add_argument('--manpage-urls', required=True) - p.add_argument('--revision', required=True) - p.add_argument('infile', type=Path) - p.add_argument('outfile', type=Path) - def _build_cli_html(p: argparse.ArgumentParser) -> None: p.add_argument('--manpage-urls', required=True) p.add_argument('--revision', required=True) @@ -761,11 +686,6 @@ def _build_cli_html(p: argparse.ArgumentParser) -> None: p.add_argument('infile', type=Path) p.add_argument('outfile', type=Path) -def _run_cli_db(args: argparse.Namespace) -> None: - with open(args.manpage_urls, 'r') as manpage_urls: - md = DocBookConverter(json.load(manpage_urls), args.revision) - md.convert(args.infile, args.outfile) - def _run_cli_html(args: argparse.Namespace) -> None: with open(args.manpage_urls, 'r') as manpage_urls: md = HTMLConverter( @@ -777,13 +697,10 @@ def _run_cli_html(args: argparse.Namespace) -> None: def build_cli(p: argparse.ArgumentParser) -> None: formats = p.add_subparsers(dest='format', required=True) - _build_cli_db(formats.add_parser('docbook')) _build_cli_html(formats.add_parser('html')) def run_cli(args: argparse.Namespace) -> None: - if args.format == 'docbook': - _run_cli_db(args) - elif args.format == 'html': + if args.format == 'html': _run_cli_html(args) else: raise RuntimeError('format not hooked up', args) |