docs: render without deprecated optionsDocBook

The `optionsDocBook` function is deprecated in nixpkgs since
nixos-23.11. This commit updates the manual and manpages to
use commonmark formatted documentation instead of the deprecated
docbook format.

docs/home-manager-render-docs/home_manager_render_docs/__init__.py

@@ -0,0 +1,55 @@
+import argparse
+import sys
+import textwrap
+import traceback
+from io import StringIO
+from pprint import pprint
+
+from nixos_render_docs import manual
+from . import options
+from nixos_render_docs import parallel
+
+def pretty_print_exc(e: BaseException, *, _desc_text: str = "error") -> None:
+    print(f"\x1b[1;31m{_desc_text}:\x1b[0m", file=sys.stderr)
+    # destructure Exception and RuntimeError specifically so we can show nice
+    # messages for errors that weren't given their own exception type with
+    # a good pretty-printer.
+    if type(e) is Exception or type(e) is RuntimeError:
+        args = e.args
+        if len(args) and isinstance(args[0], str):
+            print("\t", args[0], file=sys.stderr, sep="")
+            args = args[1:]
+        buf = StringIO()
+        for arg in args:
+            pprint(arg, stream=buf)
+        if extra_info := buf.getvalue():
+            print("\x1b[1;34mextra info:\x1b[0m", file=sys.stderr)
+            print(textwrap.indent(extra_info, "\t"), file=sys.stderr, end="")
+    else:
+        print(e)
+    if e.__cause__ is not None:
+        print("", file=sys.stderr)
+        pretty_print_exc(e.__cause__, _desc_text="caused by")
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description='render nixos manual bits')
+    parser.add_argument('-j', '--jobs', type=int, default=None)
+
+    commands = parser.add_subparsers(dest='command', required=True)
+
+    options.build_cli(commands.add_parser('options'))
+    manual.build_cli(commands.add_parser('manual'))
+
+    args = parser.parse_args()
+    try:
+        parallel.pool_processes = args.jobs
+        if args.command == 'options':
+            options.run_cli(args)
+        elif args.command == 'manual':
+            manual.run_cli(args)
+        else:
+            raise RuntimeError('command not hooked up', args)
+    except Exception as e:
+        traceback.print_exc()
+        pretty_print_exc(e)
+        sys.exit(1)

docs/home-manager-render-docs/home_manager_render_docs/options.py

@@ -0,0 +1,129 @@
+import argparse
+import json
+from nixos_render_docs.options import (
+    DocBookConverter,
+    ManpageConverter,
+    CommonMarkConverter,
+    AsciiDocConverter,
+    _build_cli_db,
+    _build_cli_manpage,
+    _build_cli_asciidoc,
+    _build_cli_commonmark,
+)
+from nixos_render_docs.manpage import man_escape
+from nixos_render_docs.md import md_escape
+
+class HomeManagerManpageConverter(ManpageConverter):
+
+    def finalize(self) -> str:
+        result = []
+
+        # TODO: Update header and footer
+        result += [
+            r'''.TH "HOME-CONFIGURATION\&.NIX" "5" "01/01/1980" "Home Manager"''',
+            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}`home-configuration.nix` - Home Manager configuration specification'),
+            r'''.SH "DESCRIPTION"''',
+            r'''.PP''',
+            self._render('The file {file}`~/.config/home-manager/home.nix` contains the '
+                        'declarative specification of your Home Manager configuration. '
+                        'The command {command}`home-manager` takes this file and '
+                        'realises the user environment configuration specified therein.'),
+            r'''.SH "OPTIONS"''',
+            r'''.PP''',
+            self._render('You can use the following options in {file}`home-configuration.nix`.'),
+        ]
+
+        for (name, opt) in self._sorted_options():
+            result += [
+                ".PP",
+                f"\\fB{man_escape(name)}\\fR",
+                ".RS 4",
+            ]
+            result += opt.lines
+            if links := opt.links:
+                result.append(self.__option_block_separator__)
+                md_links = ""
+                for i in range(0, len(links)):
+                    md_links += "\n" if i > 0 else ""
+                    if links[i].startswith('#opt-'):
+                        md_links += f"{i+1}. see the {{option}}`{self._options_by_id[links[i]]}` option"
+                    else:
+                        md_links += f"{i+1}. " + md_escape(links[i])
+                result.append(self._render(md_links))
+
+            result.append(".RE")
+
+        result += [
+            r'''.SH "AUTHORS"''',
+            r'''.PP''',
+            r'''Home Manager contributors''',
+        ]
+
+        return "\n".join(result)
+
+
+def _run_cli_db(args: argparse.Namespace) -> None:
+    with open(args.manpage_urls, 'r') as manpage_urls:
+        md = DocBookConverter(
+            json.load(manpage_urls),
+            revision = args.revision,
+            document_type = args.document_type,
+            varlist_id = args.varlist_id,
+            id_prefix = args.id_prefix)
+
+        with open(args.infile, 'r') as f:
+            md.add_options(json.load(f))
+        with open(args.outfile, 'w') as f:
+            f.write(md.finalize())
+
+def _run_cli_manpage(args: argparse.Namespace) -> None:
+    md = HomeManagerManpageConverter(revision = args.revision)
+
+    with open(args.infile, 'r') as f:
+        md.add_options(json.load(f))
+    with open(args.outfile, 'w') as f:
+        f.write(md.finalize())
+
+def _run_cli_commonmark(args: argparse.Namespace) -> None:
+    with open(args.manpage_urls, 'r') as manpage_urls:
+        md = CommonMarkConverter(json.load(manpage_urls), revision = args.revision)
+
+        with open(args.infile, 'r') as f:
+            md.add_options(json.load(f))
+        with open(args.outfile, 'w') as f:
+            f.write(md.finalize())
+
+def _run_cli_asciidoc(args: argparse.Namespace) -> None:
+    with open(args.manpage_urls, 'r') as manpage_urls:
+        md = AsciiDocConverter(json.load(manpage_urls), revision = args.revision)
+
+        with open(args.infile, 'r') as f:
+            md.add_options(json.load(f))
+        with open(args.outfile, 'w') as f:
+            f.write(md.finalize())
+
+def build_cli(p: argparse.ArgumentParser) -> None:
+    formats = p.add_subparsers(dest='format', required=True)
+    _build_cli_db(formats.add_parser('docbook'))
+    _build_cli_manpage(formats.add_parser('manpage'))
+    _build_cli_commonmark(formats.add_parser('commonmark'))
+    _build_cli_asciidoc(formats.add_parser('asciidoc'))
+
+def run_cli(args: argparse.Namespace) -> None:
+    if args.format == 'docbook':
+        _run_cli_db(args)
+    elif args.format == 'manpage':
+        _run_cli_manpage(args)
+    elif args.format == 'commonmark':
+        _run_cli_commonmark(args)
+    elif args.format == 'asciidoc':
+        _run_cli_asciidoc(args)
+    else:
+        raise RuntimeError('format not hooked up', args)