From be6a25368f2189df579b02ab1198f9f55487d573 Mon Sep 17 00:00:00 2001 From: pennae Date: Wed, 25 Jan 2023 19:19:35 +0100 Subject: [PATCH] nixos-render-docs: init from optionsToDocbook.py this new package shall eventually contain the rendering code necessary to produce the entirety of the nixos (not nixpkgs) manual, in all of its various output formats. --- nixos/lib/make-options-doc/default.nix | 27 +----- pkgs/tools/nix/nixos-render-docs/default.nix | 60 ++++++++++++ .../src/nixos_render_docs/__init__.py | 97 ++++++++++--------- .../nix/nixos-render-docs/src/pyproject.toml | 15 +++ pkgs/top-level/all-packages.nix | 2 + 5 files changed, 128 insertions(+), 73 deletions(-) create mode 100644 pkgs/tools/nix/nixos-render-docs/default.nix rename nixos/lib/make-options-doc/optionsToDocbook.py => pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/__init__.py (87%) create mode 100644 pkgs/tools/nix/nixos-render-docs/src/pyproject.toml diff --git a/nixos/lib/make-options-doc/default.nix b/nixos/lib/make-options-doc/default.nix index b7a47f9713e6..963ebdf41e69 100644 --- a/nixos/lib/make-options-doc/default.nix +++ b/nixos/lib/make-options-doc/default.nix @@ -155,33 +155,10 @@ in rec { OTD_REVISION = revision; nativeBuildInputs = [ - (let - # python3Minimal can't be overridden with packages on Darwin, due to a missing framework. - # Instead of modifying stdenv, we take the easy way out, since most people on Darwin will - # just be hacking on the Nixpkgs manual (which also uses make-options-doc). - python = if pkgs.stdenv.isDarwin then pkgs.python3 else pkgs.python3Minimal; - self = (python.override { - inherit self; - includeSiteCustomize = true; - }); - in self.withPackages (p: - let - # TODO add our own small test suite when rendering is split out into a new tool - markdown-it-py = p.markdown-it-py.override { - disableTests = true; - }; - mdit-py-plugins = p.mdit-py-plugins.override { - inherit markdown-it-py; - disableTests = true; - }; - in [ - markdown-it-py - mdit-py-plugins - p.frozendict - ])) + pkgs.nixos-render-docs ]; } '' - python ${./optionsToDocbook.py} \ + nixos-render-docs \ ${lib.optionalString markdownByDefault "--markdown-by-default"} \ ${optionsJSON}/share/doc/nixos/options.json \ > options.xml diff --git a/pkgs/tools/nix/nixos-render-docs/default.nix b/pkgs/tools/nix/nixos-render-docs/default.nix new file mode 100644 index 000000000000..1e1036537c23 --- /dev/null +++ b/pkgs/tools/nix/nixos-render-docs/default.nix @@ -0,0 +1,60 @@ +{ lib +, stdenv +, python3 +, python3Minimal +}: + +let + # python3Minimal can't be overridden with packages on Darwin, due to a missing framework. + # Instead of modifying stdenv, we take the easy way out, since most people on Darwin will + # just be hacking on the Nixpkgs manual (which also uses make-options-doc). + python = ((if stdenv.isDarwin then python3 else python3Minimal).override { + self = python; + includeSiteCustomize = true; + }); + + # TODO add our own small test suite, maybe add tests for these deps to channels? + markdown-it-py-no-tests = python.pkgs.markdown-it-py.override { + disableTests = true; + }; + mdit-py-plugins-no-tests = python.pkgs.mdit-py-plugins.override { + markdown-it-py = markdown-it-py-no-tests; + disableTests = true; + }; +in + +python.pkgs.buildPythonApplication { + pname = "nixos-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 = ./src; + }; + + nativeBuildInputs = [ + python.pkgs.setuptools + ]; + + propagatedBuildInputs = [ + markdown-it-py-no-tests + mdit-py-plugins-no-tests + python.pkgs.frozendict + ]; + + meta = with lib; { + description = "Renderer for NixOS manual and option docs"; + license = licenses.mit; + maintainers = [ ]; + }; +} diff --git a/nixos/lib/make-options-doc/optionsToDocbook.py b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/__init__.py similarity index 87% rename from nixos/lib/make-options-doc/optionsToDocbook.py rename to pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/__init__.py index adb009745e33..350f324b33cf 100644 --- a/nixos/lib/make-options-doc/optionsToDocbook.py +++ b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/__init__.py @@ -344,56 +344,57 @@ def print_decl_def(header, locs): print(f"""{escape(loc['name'])}""") print(f"""""") -markdownByDefault = False -optOffset = 0 -for arg in sys.argv[1:]: - if arg == "--markdown-by-default": - optOffset += 1 - markdownByDefault = True +def main(): + markdownByDefault = False + optOffset = 0 + for arg in sys.argv[1:]: + if arg == "--markdown-by-default": + optOffset += 1 + markdownByDefault = True -options = convertMD(json.load(open(sys.argv[1 + optOffset], 'r'))) + options = convertMD(json.load(open(sys.argv[1 + optOffset], 'r'))) -keys = list(options.keys()) -keys.sort(key=lambda opt: [ (0 if p.startswith("enable") else 1 if p.startswith("package") else 2, p) - for p in options[opt]['loc'] ]) + keys = list(options.keys()) + keys.sort(key=lambda opt: [ (0 if p.startswith("enable") else 1 if p.startswith("package") else 2, p) + for p in options[opt]['loc'] ]) -print(f"""""") -if OTD_DOCUMENT_TYPE == 'appendix': - print("""""") - print(""" Configuration Options""") -print(f"""""") + print(f"""""") + if OTD_DOCUMENT_TYPE == 'appendix': + print("""""") + print(""" Configuration Options""") + print(f"""""") -for name in keys: - opt = options[name] - id = OTD_OPTION_ID_PREFIX + name.translate(id_translate_table) - print(f"""""") - # NOTE adding extra spaces here introduces spaces into xref link expansions - print(f"""""", end='') - print(f"""""", end='') - print(f"""""") - print(f"""""") - print(opt['description']) - if typ := opt.get('type'): - print(typ) - if default := opt.get('default'): - print(default) - if example := opt.get('example'): - print(example) - if related := opt.get('relatedPackages'): - print(f"""""") - print(f""" Related packages:""") - print(f"""""") - print(related) - if decl := opt.get('declarations'): - print_decl_def("Declared by", decl) - if defs := opt.get('definitions'): - print_decl_def("Defined by", defs) - print(f"""""") - print(f"""""") + for name in keys: + opt = options[name] + id = OTD_OPTION_ID_PREFIX + name.translate(id_translate_table) + print(f"""""") + # NOTE adding extra spaces here introduces spaces into xref link expansions + print(f"""""", end='') + print(f"""""", end='') + print(f"""""") + print(f"""""") + print(opt['description']) + if typ := opt.get('type'): + print(typ) + if default := opt.get('default'): + print(default) + if example := opt.get('example'): + print(example) + if related := opt.get('relatedPackages'): + print(f"""""") + print(f""" Related packages:""") + print(f"""""") + print(related) + if decl := opt.get('declarations'): + print_decl_def("Declared by", decl) + if defs := opt.get('definitions'): + print_decl_def("Defined by", defs) + print(f"""""") + print(f"""""") -print("""""") -if OTD_DOCUMENT_TYPE == 'appendix': - print("""""") + print("""""") + if OTD_DOCUMENT_TYPE == 'appendix': + print("""""") diff --git a/pkgs/tools/nix/nixos-render-docs/src/pyproject.toml b/pkgs/tools/nix/nixos-render-docs/src/pyproject.toml new file mode 100644 index 000000000000..d66643ef8421 --- /dev/null +++ b/pkgs/tools/nix/nixos-render-docs/src/pyproject.toml @@ -0,0 +1,15 @@ +[project] +name = "nixos-render-docs" +version = "0.0" +description = "Renderer for NixOS manual and option docs" +classifiers = [ + "Programming Language :: Python :: 3", + "License :: OSI Approved :: MIT License", + "Operating System :: OS Independent", +] + +[project.scripts] +nixos-render-docs = "nixos_render_docs:main" + +[build-system] +requires = ["setuptools"] diff --git a/pkgs/top-level/all-packages.nix b/pkgs/top-level/all-packages.nix index 87fc70d7834a..fb9cd3334bc4 100644 --- a/pkgs/top-level/all-packages.nix +++ b/pkgs/top-level/all-packages.nix @@ -37557,6 +37557,8 @@ with pkgs; nixos-install-tools = callPackage ../tools/nix/nixos-install-tools { }; + nixos-render-docs = callPackage ../tools/nix/nixos-render-docs { }; + nixdoc = callPackage ../tools/nix/nixdoc {}; dnadd = callPackage ../tools/nix/dnadd { };