docs: use nixos-render-docs

This commit removes the `home-manager-render-docs` package in favor
of upstream `nixos-render-docs` where the manpage generator has been
updated to take a `--header` and a `--footer` flag specifying static
content around the content derived from the options.json file.

docs/default.nix

@@ -92,41 +92,35 @@ let
     optionIdPrefix = "nix-darwin-opt-";
   };
 
-  # home-manager specialized version of nixos-render-docs
-  home-manager-render-docs = let python = pkgs.buildPackages.python3;
-  in python.pkgs.callPackage ./home-manager-render-docs.nix {
-    python = python;
-    nixos-render-docs = python.pkgs.toPythonModule pkgs.nixos-render-docs;
-  };
-
   release-config = builtins.fromJSON (builtins.readFile ../release.json);
   revision = "release-${release-config.release}";
   # Generate the `man home-configuration.nix` package
   home-configuration-manual =
     pkgs.runCommand "home-configuration-reference-manpage" {
       nativeBuildInputs =
-        [ pkgs.buildPackages.installShellFiles home-manager-render-docs ];
+        [ pkgs.buildPackages.installShellFiles pkgs.nixos-render-docs ];
       allowedReferences = [ "out" ];
     } ''
       # Generate manpages.
       mkdir -p $out/share/man/man5
       mkdir -p $out/share/man/man1
-      home-manager-render-docs -j $NIX_BUILD_CORES options manpage \
+      nixos-render-docs -j $NIX_BUILD_CORES options manpage \
         --revision ${revision} \
+        --header ${./home-configuration-nix-header.5} \
+        --footer ${./home-configuration-nix-footer.5} \
         ${hmOptionsDocs.optionsJSON}/share/doc/nixos/options.json \
         $out/share/man/man5/home-configuration.nix.5
       cp ${./home-manager.1} $out/share/man/man1/home-manager.1
     '';
   # Generate the HTML manual pages
   home-manager-manual = pkgs.callPackage ./home-manager-manual.nix {
-    optionsDoc = hmOptionsDocs;
     nmd = nmdSrc;
     home-manager-options = {
       home-manager = hmOptionsDocs.optionsJSON;
       nixos = nixosOptionsDocs.optionsJSON;
       nix-darwin = nixDarwinOptionsDocs.optionsJSON;
     };
-    inherit revision home-manager-render-docs;
+    inherit revision;
   };
   html = home-manager-manual;
   htmlOpenTool = pkgs.callPackage ./html-open-tool.nix { } { inherit html; };

docs/home-configuration-nix-footer.5

@@ -0,0 +1,3 @@
+.SH "AUTHORS"
+.PP
+Home Manager contributors

docs/home-configuration-nix-header.5

@@ -0,0 +1,9 @@
+.TH "HOME-CONFIGURATION\&.NIX" "5" "01/01/1980" "Home Manager"
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" enable line breaks after slashes
+.cflags 4 /
+.SH "NAME"
+\fIhome\-configuration\&.nix\fP \- Home Manager configuration specification

docs/home-manager-manual.nix

@@ -1,10 +1,10 @@
-{ stdenv, home-manager-render-docs, optionsDoc, lib, documentation-highlighter
+{ stdenv, lib, documentation-highlighter, nmd, revision, home-manager-options
-, nmd, revision, home-manager-options }:
+, nixos-render-docs }:
 let outputPath = "share/doc/home-manager";
 in stdenv.mkDerivation {
   name = "nixpkgs-manual";
 
-  nativeBuildInputs = [ home-manager-render-docs ];
+  nativeBuildInputs = [ nixos-render-docs ];
 
   src = ./manual;
 
@@ -33,7 +33,7 @@ in stdenv.mkDerivation {
         '@OPTIONS_JSON@' \
         ${home-manager-options.nix-darwin}/share/doc/nixos/options.json
 
-    home-manager-render-docs manual html \
+    nixos-render-docs manual html \
       --manpage-urls ./manpage-urls.json \
       --revision ${lib.trivial.revisionWithDefault revision} \
       --stylesheet ${nmd}/static/style.css \

docs/home-manager-render-docs.nix

@@ -1,27 +0,0 @@
-{ buildPythonApplication, lib, python, nixos-render-docs }:
-buildPythonApplication {
-  pname = "home-manager-render-docs";
-  version = "0.0";
-  format = "pyproject";
-
-  src = lib.cleanSourceWith {
-    filter = name: type:
-      lib.cleanSourceFilter name type && !(type == "directory"
-        && builtins.elem (baseNameOf name) [
-          ".pytest_cache"
-          ".mypy_cache"
-          "__pycache__"
-        ]);
-    src = ./home-manager-render-docs;
-  };
-
-  nativeBuildInputs = with python.pkgs; [ setuptools ];
-
-  propagatedBuildInputs = [ nixos-render-docs ];
-
-  meta = with lib; {
-    description = "Renderer for home-manager manual and option docs";
-    license = licenses.mit;
-    maintainers = [ ];
-  };
-}

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

@@ -1,55 +0,0 @@
-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

@@ -1,129 +0,0 @@
-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)

docs/home-manager-render-docs/pyproject.toml

@@ -1,18 +0,0 @@
-[project]
-name = "home-manager-render-docs"
-version = "0.0"
-description = "Renderer for Home Manager manual and option docs"
-classifiers = [
-    "Programming Language :: Python :: 3",
-    "License :: OSI Approved :: MIT License",
-    "Operating System :: OS Independent",
-]
-dependencies = [
-  "nixos-render-docs"
-]
-
-[project.scripts]
-home-manager-render-docs = "home_manager_render_docs:main"
-
-[build-system]
-requires = ["setuptools"]

flake.lock

@@ -2,11 +2,11 @@
   "nodes": {
     "nixpkgs": {
       "locked": {
-        "lastModified": 1701253981,
+        "lastModified": 1701718080,
-        "narHash": "sha256-ztaDIyZ7HrTAfEEUt9AtTDNoCYxUdSd6NrRHaYOIxtk=",
+        "narHash": "sha256-6ovz0pG76dE0P170pmmZex1wWcQoeiomUZGggfH9XPs=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "e92039b55bcd58469325ded85d4f58dd5a4eaf58",
+        "rev": "2c7f3c0fb7c08a0814627611d9d7d45ab6d75335",
         "type": "github"
       },
       "original": {