eeva
/
home-manager
mirror of https://github.com/nix-community/home-manager
1
0
Fork 0
Code Issues Releases Wiki Activity

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.
This commit is contained in:
Viktor Kronvall 2023-11-25 23:29:26 +09:00
parent e4d290396c
commit 8dae2041ef
9 changed files with 24 additions and 247 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
docs/default.nix
View File

@ -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; };

3
docs/home-configuration-nix-footer.5 Normal file
View File

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

9
docs/home-configuration-nix-header.5 Normal file
View File

@ -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

8
docs/home-manager-manual.nix
View File

@ -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 \

27
docs/home-manager-render-docs.nix
View File

@ -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 = [ ];
};
}

55
docs/home-manager-render-docs/home_manager_render_docs/__init__.py
View File

@ -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)

129
docs/home-manager-render-docs/home_manager_render_docs/options.py
View File

@ -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)

18
docs/home-manager-render-docs/pyproject.toml
View File

@ -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"]

6
flake.lock
View File

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