From 9bfa2e36a258d81feed09bea5c4f777f33436003 Mon Sep 17 00:00:00 2001 From: Viktor Kronvall Date: Sat, 25 Nov 2023 23:04:10 +0900 Subject: [PATCH 1/2] nixos-render-docs: take header and footer on CLI This commit generalizes nixos-render-docs for manpage generation to take the header preamble and footer postscript as file paths as CLI flags --header and --footer. --- .../src/nixos_render_docs/options.py | 80 ++++++++++++------- 1 file changed, 52 insertions(+), 28 deletions(-) diff --git a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/options.py b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/options.py index 2813ffcf8bc0..734339c0df64 100644 --- a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/options.py +++ b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/options.py @@ -8,6 +8,7 @@ import xml.sax.saxutils as xml from abc import abstractmethod from collections.abc import Mapping, Sequence from markdown_it.token import Token +from pathlib import Path from typing import Any, Generic, Optional from urllib.parse import quote @@ -287,18 +288,27 @@ class ManpageConverter(BaseConverter[OptionsManpageRenderer]): _links_in_last_description: Optional[list[str]] = None def __init__(self, revision: str, + header: Path | None, + footer: Path | None, *, # only for parallel rendering _options_by_id: Optional[dict[str, str]] = None): super().__init__(revision) self._options_by_id = _options_by_id or {} self._renderer = OptionsManpageRenderer({}, self._options_by_id) + self._header = header + self._footer = footer def _parallel_render_prepare(self) -> Any: - return (self._revision, { '_options_by_id': self._options_by_id }) + return ( + self._revision, + self._header, + self._footer, + { '_options_by_id': self._options_by_id }, + ) @classmethod def _parallel_render_init_worker(cls, a: Any) -> ManpageConverter: - return cls(a[0], **a[1]) + return cls(a[0], a[1], a[2], **a[3]) def _render_option(self, name: str, option: dict[str, Any]) -> RenderedOption: links = self._renderer.link_footnotes = [] @@ -342,26 +352,30 @@ class ManpageConverter(BaseConverter[OptionsManpageRenderer]): def finalize(self) -> str: result = [] - result += [ - r'''.TH "CONFIGURATION\&.NIX" "5" "01/01/1980" "NixOS" "NixOS Reference Pages"''', - r'''.\" disable hyphenation''', - r'''.nh''', - r'''.\" disable justification (adjust text to left margin only)''', - r'''.ad l''', - r'''.\" enable line breaks after slashes''', - r'''.cflags 4 /''', - r'''.SH "NAME"''', - self._render('{file}`configuration.nix` - NixOS system configuration specification'), - r'''.SH "DESCRIPTION"''', - r'''.PP''', - self._render('The file {file}`/etc/nixos/configuration.nix` contains the ' - 'declarative specification of your NixOS system configuration. ' - 'The command {command}`nixos-rebuild` takes this file and ' - 'realises the system configuration specified therein.'), - r'''.SH "OPTIONS"''', - r'''.PP''', - self._render('You can use the following options in {file}`configuration.nix`.'), - ] + if self._header is not None: + with self._header.open() as f: + result += f.read().splitlines() + else: + result += [ + r'''.TH "CONFIGURATION\&.NIX" "5" "01/01/1980" "NixOS" "NixOS Reference Pages"''', + r'''.\" disable hyphenation''', + r'''.nh''', + r'''.\" disable justification (adjust text to left margin only)''', + r'''.ad l''', + r'''.\" enable line breaks after slashes''', + r'''.cflags 4 /''', + r'''.SH "NAME"''', + self._render('{file}`configuration.nix` - NixOS system configuration specification'), + r'''.SH "DESCRIPTION"''', + r'''.PP''', + self._render('The file {file}`/etc/nixos/configuration.nix` contains the ' + 'declarative specification of your NixOS system configuration. ' + 'The command {command}`nixos-rebuild` takes this file and ' + 'realises the system configuration specified therein.'), + r'''.SH "OPTIONS"''', + r'''.PP''', + self._render('You can use the following options in {file}`configuration.nix`.'), + ] for (name, opt) in self._sorted_options(): result += [ @@ -383,11 +397,15 @@ class ManpageConverter(BaseConverter[OptionsManpageRenderer]): result.append(".RE") - result += [ - r'''.SH "AUTHORS"''', - r'''.PP''', - r'''Eelco Dolstra and the Nixpkgs/NixOS contributors''', - ] + if self._footer is not None: + with self._footer.open() as f: + result += f.read().splitlines() + else: + result += [ + r'''.SH "AUTHORS"''', + r'''.PP''', + r'''Eelco Dolstra and the Nixpkgs/NixOS contributors''', + ] return "\n".join(result) @@ -573,6 +591,8 @@ def _build_cli_db(p: argparse.ArgumentParser) -> None: def _build_cli_manpage(p: argparse.ArgumentParser) -> None: p.add_argument('--revision', required=True) + p.add_argument("--header", type=Path) + p.add_argument("--footer", type=Path) p.add_argument("infile") p.add_argument("outfile") @@ -603,7 +623,11 @@ def _run_cli_db(args: argparse.Namespace) -> None: f.write(md.finalize()) def _run_cli_manpage(args: argparse.Namespace) -> None: - md = ManpageConverter(revision = args.revision) + md = ManpageConverter( + revision = args.revision, + header = args.header, + footer = args.footer, + ) with open(args.infile, 'r') as f: md.add_options(json.load(f)) From 98ba0aed731dbcb0f1facd29bb9398630adaa141 Mon Sep 17 00:00:00 2001 From: Viktor Kronvall Date: Sun, 26 Nov 2023 00:39:19 +0900 Subject: [PATCH 2/2] nixos-render-docs: header and footer as list[str] --- .../src/nixos_render_docs/options.py | 25 +++++++++++++------ 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/options.py b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/options.py index 734339c0df64..d0229e074c54 100644 --- a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/options.py +++ b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/options.py @@ -288,8 +288,8 @@ class ManpageConverter(BaseConverter[OptionsManpageRenderer]): _links_in_last_description: Optional[list[str]] = None def __init__(self, revision: str, - header: Path | None, - footer: Path | None, + header: list[str] | None, + footer: list[str] | None, *, # only for parallel rendering _options_by_id: Optional[dict[str, str]] = None): @@ -353,8 +353,7 @@ class ManpageConverter(BaseConverter[OptionsManpageRenderer]): result = [] if self._header is not None: - with self._header.open() as f: - result += f.read().splitlines() + result += self._header else: result += [ r'''.TH "CONFIGURATION\&.NIX" "5" "01/01/1980" "NixOS" "NixOS Reference Pages"''', @@ -398,8 +397,7 @@ class ManpageConverter(BaseConverter[OptionsManpageRenderer]): result.append(".RE") if self._footer is not None: - with self._footer.open() as f: - result += f.read().splitlines() + result += self._footer else: result += [ r'''.SH "AUTHORS"''', @@ -623,10 +621,21 @@ def _run_cli_db(args: argparse.Namespace) -> None: f.write(md.finalize()) def _run_cli_manpage(args: argparse.Namespace) -> None: + header = None + footer = None + + if args.header is not None: + with args.header.open() as f: + header = f.read().splitlines() + + if args.footer is not None: + with args.footer.open() as f: + footer = f.read().splitlines() + md = ManpageConverter( revision = args.revision, - header = args.header, - footer = args.footer, + header = header, + footer = footer, ) with open(args.infile, 'r') as f: