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:
parent
e4d290396c
commit
8dae2041ef
9 changed files with 24 additions and 247 deletions
|
@ -92,41 +92,35 @@ let
|
||||||
optionIdPrefix = "nix-darwin-opt-";
|
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);
|
release-config = builtins.fromJSON (builtins.readFile ../release.json);
|
||||||
revision = "release-${release-config.release}";
|
revision = "release-${release-config.release}";
|
||||||
# Generate the `man home-configuration.nix` package
|
# Generate the `man home-configuration.nix` package
|
||||||
home-configuration-manual =
|
home-configuration-manual =
|
||||||
pkgs.runCommand "home-configuration-reference-manpage" {
|
pkgs.runCommand "home-configuration-reference-manpage" {
|
||||||
nativeBuildInputs =
|
nativeBuildInputs =
|
||||||
[ pkgs.buildPackages.installShellFiles home-manager-render-docs ];
|
[ pkgs.buildPackages.installShellFiles pkgs.nixos-render-docs ];
|
||||||
allowedReferences = [ "out" ];
|
allowedReferences = [ "out" ];
|
||||||
} ''
|
} ''
|
||||||
# Generate manpages.
|
# Generate manpages.
|
||||||
mkdir -p $out/share/man/man5
|
mkdir -p $out/share/man/man5
|
||||||
mkdir -p $out/share/man/man1
|
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} \
|
--revision ${revision} \
|
||||||
|
--header ${./home-configuration-nix-header.5} \
|
||||||
|
--footer ${./home-configuration-nix-footer.5} \
|
||||||
${hmOptionsDocs.optionsJSON}/share/doc/nixos/options.json \
|
${hmOptionsDocs.optionsJSON}/share/doc/nixos/options.json \
|
||||||
$out/share/man/man5/home-configuration.nix.5
|
$out/share/man/man5/home-configuration.nix.5
|
||||||
cp ${./home-manager.1} $out/share/man/man1/home-manager.1
|
cp ${./home-manager.1} $out/share/man/man1/home-manager.1
|
||||||
'';
|
'';
|
||||||
# Generate the HTML manual pages
|
# Generate the HTML manual pages
|
||||||
home-manager-manual = pkgs.callPackage ./home-manager-manual.nix {
|
home-manager-manual = pkgs.callPackage ./home-manager-manual.nix {
|
||||||
optionsDoc = hmOptionsDocs;
|
|
||||||
nmd = nmdSrc;
|
nmd = nmdSrc;
|
||||||
home-manager-options = {
|
home-manager-options = {
|
||||||
home-manager = hmOptionsDocs.optionsJSON;
|
home-manager = hmOptionsDocs.optionsJSON;
|
||||||
nixos = nixosOptionsDocs.optionsJSON;
|
nixos = nixosOptionsDocs.optionsJSON;
|
||||||
nix-darwin = nixDarwinOptionsDocs.optionsJSON;
|
nix-darwin = nixDarwinOptionsDocs.optionsJSON;
|
||||||
};
|
};
|
||||||
inherit revision home-manager-render-docs;
|
inherit revision;
|
||||||
};
|
};
|
||||||
html = home-manager-manual;
|
html = home-manager-manual;
|
||||||
htmlOpenTool = pkgs.callPackage ./html-open-tool.nix { } { inherit html; };
|
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
|
{ stdenv, lib, documentation-highlighter, nmd, revision, home-manager-options
|
||||||
, nmd, revision, home-manager-options }:
|
, nixos-render-docs }:
|
||||||
let outputPath = "share/doc/home-manager";
|
let outputPath = "share/doc/home-manager";
|
||||||
in stdenv.mkDerivation {
|
in stdenv.mkDerivation {
|
||||||
name = "nixpkgs-manual";
|
name = "nixpkgs-manual";
|
||||||
|
|
||||||
nativeBuildInputs = [ home-manager-render-docs ];
|
nativeBuildInputs = [ nixos-render-docs ];
|
||||||
|
|
||||||
src = ./manual;
|
src = ./manual;
|
||||||
|
|
||||||
|
@ -33,7 +33,7 @@ in stdenv.mkDerivation {
|
||||||
'@OPTIONS_JSON@' \
|
'@OPTIONS_JSON@' \
|
||||||
${home-manager-options.nix-darwin}/share/doc/nixos/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 \
|
--manpage-urls ./manpage-urls.json \
|
||||||
--revision ${lib.trivial.revisionWithDefault revision} \
|
--revision ${lib.trivial.revisionWithDefault revision} \
|
||||||
--stylesheet ${nmd}/static/style.css \
|
--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": {
|
"nodes": {
|
||||||
"nixpkgs": {
|
"nixpkgs": {
|
||||||
"locked": {
|
"locked": {
|
||||||
"lastModified": 1701253981,
|
"lastModified": 1701718080,
|
||||||
"narHash": "sha256-ztaDIyZ7HrTAfEEUt9AtTDNoCYxUdSd6NrRHaYOIxtk=",
|
"narHash": "sha256-6ovz0pG76dE0P170pmmZex1wWcQoeiomUZGggfH9XPs=",
|
||||||
"owner": "NixOS",
|
"owner": "NixOS",
|
||||||
"repo": "nixpkgs",
|
"repo": "nixpkgs",
|
||||||
"rev": "e92039b55bcd58469325ded85d4f58dd5a4eaf58",
|
"rev": "2c7f3c0fb7c08a0814627611d9d7d45ab6d75335",
|
||||||
"type": "github"
|
"type": "github"
|
||||||
},
|
},
|
||||||
"original": {
|
"original": {
|
||||||
|
|
Loading…
Reference in a new issue