mirror of
https://github.com/nix-community/home-manager.git
synced 2024-12-14 11:57:55 +00:00
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
parent
e4d290396c
commit
8dae2041ef
9 changed files with 24 additions and 247 deletions
|
|
@ -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
3
docs/home-configuration-nix-footer.5
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
.SH "AUTHORS"
|
||||
.PP
|
||||
Home Manager contributors
|
||||
9
docs/home-configuration-nix-header.5
Normal file
9
docs/home-configuration-nix-header.5
Normal 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
|
||||
|
|
@ -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 \
|
||||
|
|
|
|||
|
|
@ -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 = [ ];
|
||||
};
|
||||
}
|
||||
|
|
@ -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)
|
||||
|
|
@ -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)
|
||||
|
|
@ -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"]
|
||||
|
|
@ -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": {
|
||||
|
|
|
|||
Loading…
Reference in a new issue