From cc48491bfc236406421c1ce38e062e9466206c28 Mon Sep 17 00:00:00 2001 From: Viktor Kronvall Date: Sat, 25 Nov 2023 23:29:26 +0900 Subject: [PATCH] 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 | 16 +-- docs/home-configuration-nix-footer.5 | 3 + docs/home-configuration-nix-header.5 | 9 ++ docs/home-manager-manual.nix | 8 +- docs/home-manager-render-docs.nix | 27 ---- .../home_manager_render_docs/__init__.py | 55 -------- .../home_manager_render_docs/options.py | 129 ------------------ docs/home-manager-render-docs/pyproject.toml | 18 --- flake.lock | 6 +- 9 files changed, 24 insertions(+), 247 deletions(-) create mode 100644 docs/home-configuration-nix-footer.5 create mode 100644 docs/home-configuration-nix-header.5 delete mode 100644 docs/home-manager-render-docs.nix delete mode 100644 docs/home-manager-render-docs/home_manager_render_docs/__init__.py delete mode 100644 docs/home-manager-render-docs/home_manager_render_docs/options.py delete mode 100644 docs/home-manager-render-docs/pyproject.toml diff --git a/docs/default.nix b/docs/default.nix index de7fb4b67..0c2c55160 100644 --- a/docs/default.nix +++ b/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; }; diff --git a/docs/home-configuration-nix-footer.5 b/docs/home-configuration-nix-footer.5 new file mode 100644 index 000000000..c10988130 --- /dev/null +++ b/docs/home-configuration-nix-footer.5 @@ -0,0 +1,3 @@ +.SH "AUTHORS" +.PP +Home Manager contributors diff --git a/docs/home-configuration-nix-header.5 b/docs/home-configuration-nix-header.5 new file mode 100644 index 000000000..9e562801b --- /dev/null +++ b/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 diff --git a/docs/home-manager-manual.nix b/docs/home-manager-manual.nix index a4c94ea99..8e1bf6ec3 100644 --- a/docs/home-manager-manual.nix +++ b/docs/home-manager-manual.nix @@ -1,10 +1,10 @@ -{ stdenv, home-manager-render-docs, optionsDoc, lib, documentation-highlighter -, nmd, revision, home-manager-options }: +{ stdenv, lib, documentation-highlighter, 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 \ diff --git a/docs/home-manager-render-docs.nix b/docs/home-manager-render-docs.nix deleted file mode 100644 index af80d396a..000000000 --- a/docs/home-manager-render-docs.nix +++ /dev/null @@ -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 = [ ]; - }; -} diff --git a/docs/home-manager-render-docs/home_manager_render_docs/__init__.py b/docs/home-manager-render-docs/home_manager_render_docs/__init__.py deleted file mode 100644 index dbec27b3a..000000000 --- a/docs/home-manager-render-docs/home_manager_render_docs/__init__.py +++ /dev/null @@ -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) diff --git a/docs/home-manager-render-docs/home_manager_render_docs/options.py b/docs/home-manager-render-docs/home_manager_render_docs/options.py deleted file mode 100644 index 8c040d991..000000000 --- a/docs/home-manager-render-docs/home_manager_render_docs/options.py +++ /dev/null @@ -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) diff --git a/docs/home-manager-render-docs/pyproject.toml b/docs/home-manager-render-docs/pyproject.toml deleted file mode 100644 index 6357c5c72..000000000 --- a/docs/home-manager-render-docs/pyproject.toml +++ /dev/null @@ -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"] diff --git a/flake.lock b/flake.lock index cbfb8e137..42da11db7 100644 --- a/flake.lock +++ b/flake.lock @@ -2,11 +2,11 @@ "nodes": { "nixpkgs": { "locked": { - "lastModified": 1700204040, - "narHash": "sha256-xSVcS5HBYnD3LTer7Y2K8ZQCDCXMa3QUD1MzRjHzuhI=", + "lastModified": 1701718080, + "narHash": "sha256-6ovz0pG76dE0P170pmmZex1wWcQoeiomUZGggfH9XPs=", "owner": "NixOS", "repo": "nixpkgs", - "rev": "c757e9bd77b16ca2e03c89bf8bc9ecb28e0c06ad", + "rev": "2c7f3c0fb7c08a0814627611d9d7d45ab6d75335", "type": "github" }, "original": {