switch to nixos-render-docs

2023-12-03 21:19:34 -08:00 · 2023-12-03 21:19:34 -08:00 · 1b971e95b2
commit 1b971e95b2
parent 0014e5c2f7
8 changed files with 213 additions and 157 deletions
--- a/docs/default.nix
+++ b/docs/default.nix
@ -0,0 +1,120 @@
+# Taken nearly verbatim from https://github.com/nix-community/home-manager/pull/4673
+{ pkgs
+, buildPackages
+, lib
+, nmdsrc
+, stdenv
+, documentation-highlighter
+, nixos-render-docs
+
+, release
+, allModules
+}:
+
+let
+  shbPath = toString ./..;
+
+  gitHubDeclaration = user: repo: subpath:
+    let urlRef = "main";
+        end = if subpath == "" then "" else "/" + subpath;
+    in {
+      url = "https://github.com/${user}/${repo}/blob/${urlRef}${end}";
+      name = "<${repo}${end}>";
+    };
+
+  ghRoot = (gitHubDeclaration "ibizaman" "selfhostblocks" "").url;
+
+  buildOptionsDocs = args@{ modules, includeModuleSystemOptions ? true, ... }:
+    let options = (lib.evalModules { inherit modules; }).options;
+    in buildPackages.nixosOptionsDoc ({
+      options = if includeModuleSystemOptions then
+        options
+                else
+                  builtins.removeAttrs options [ "_module" ];
+      transformOptions = opt:
+        opt // {
+          # Clean up declaration sites to not refer to the Home Manager
+          # source tree.
+          declarations = map (decl:
+            gitHubDeclaration "ibizaman" "selfhostblocks"
+              (lib.removePrefix "/" (lib.removePrefix shbPath (toString decl)))) opt.declarations;
+        };
+    } // builtins.removeAttrs args [ "modules" "includeModuleSystemOptions" ]);
+
+  scrubbedModule = {
+    _module.args.pkgs = lib.mkForce (nmd.scrubDerivations "pkgs" pkgs);
+    _module.check = false;
+  };
+
+  optionsDocs = buildOptionsDocs {
+    modules = allModules ++ [ scrubbedModule ];
+    variablelistId = "selfhostblocks-options";
+    includeModuleSystemOptions = false;
+  };
+
+  nmd = import nmdsrc {
+    inherit lib;
+    # The DocBook output of `nixos-render-docs` doesn't have the change
+    # `nmd` uses to work around the broken stylesheets in
+    # `docbook-xsl-ns`, so we restore the patched version here.
+    pkgs = pkgs // {
+      docbook-xsl-ns =
+        pkgs.docbook-xsl-ns.override { withManOptDedupPatch = true; };
+    };
+  };
+
+  outputPath = "share/doc/selfhostblocks";
+
+  manpage-urls = pkgs.writeText "manpage-urls.json" ''{}'';
+in stdenv.mkDerivation {
+  name = "self-host-blocks-manual";
+
+  nativeBuildInputs = [ nixos-render-docs ];
+
+  src = ./.;
+
+  buildPhase = ''
+    mkdir -p out/media
+    mkdir -p out/highlightjs
+
+    cp -t out/highlightjs \
+      ${documentation-highlighter}/highlight.pack.js \
+      ${documentation-highlighter}/LICENSE \
+      ${documentation-highlighter}/mono-blue.css \
+      ${documentation-highlighter}/loader.js
+
+    substituteInPlace ./options.md \
+      --replace \
+        '@OPTIONS_JSON@' \
+        ${optionsDocs.optionsJSON}/share/doc/nixos/options.json
+
+    find . -name "*.md" -print0 | \
+        while IFS= read -r -d ''' f; do
+          substituteInPlace "''${f}" \
+            --replace \
+              '@REPO@' \
+              "${lib.debug.traceVal ghRoot}"
+        done
+
+    nixos-render-docs manual html \
+      --manpage-urls ${manpage-urls} \
+      --media-dir media \
+      --revision ${lib.trivial.revisionWithDefault release} \
+      --stylesheet ${nmdsrc}/static/style.css \
+      --stylesheet ${nmdsrc}/static/highlightjs/tomorrow-night.min.css \
+      --script ${nmdsrc}/static/highlightjs/highlight.min.js \
+      --script ${nmdsrc}/static/highlightjs/highlight.load.js \
+      --toc-depth 1 \
+      --section-toc-depth 1 \
+      manual.md \
+      out/index.html
+  '';
+
+  installPhase = ''
+    dest="$out/${outputPath}"
+    mkdir -p "$(dirname "$dest")"
+    mv out "$dest"
+    mkdir -p $out/nix-support/
+    echo "doc manual $dest index.html" >> $out/nix-support/hydra-build-products
+  '';
+}
--- a/docs/man-pages.xml
+++ b/docs/man-pages.xml
@ -1,37 +0,0 @@
-<!-- Copyright (c) 2019-2022, see AUTHORS. Licensed under MIT License, see LICENSE. -->
-<reference xmlns="http://docbook.org/ns/docbook"
-           xmlns:xlink="http://www.w3.org/1999/xlink"
-           xmlns:xi="http://www.w3.org/2001/XInclude">
- <title>Self Host Blocks Reference Pages</title>
- <info>
-  <author><personname>Self Host Blocks contributors</personname>
-  </author>
-  <copyright><year>2022</year><holder>Self Host Blocks contributors</holder>
-  </copyright>
- </info>
- <refentry>
-  <refmeta>
-   <refentrytitle><filename>selfhostblocks-options</filename></refentrytitle>
-   <manvolnum>5</manvolnum>
-   <refmiscinfo class="source">Self Host Blocks</refmiscinfo>
-  </refmeta>
-  <refnamediv>
-   <refname><filename>selfhostblocks-options</filename>
-   </refname><refpurpose>Self Host Blocks configuration specification</refpurpose>
-  </refnamediv>
-  <refsection>
-   <title>Description</title>
-   <para>
-    This contains the module options available for Self Host Blocks.
-   </para>
-  </refsection>
-  <refsection>
-   <title>Options</title>
-   <para>
-    You can use the following options after importing Self Host Blocks as a flake input, then
-    importing the default module for your system.
-   </para>
-   <xi:include href="./nmd-result/selfhostblocks-options.xml" />
-  </refsection>
- </refentry>
-</reference>
--- a/docs/manual.md
+++ b/docs/manual.md
@ -0,0 +1,20 @@
+# Self Host Blocks Manual {#self-host-blocks-manual}
+
+## Version 0.0.1
+
+
+```{=include=} preface
+preface.md
+```
+
+```{=include=} appendix html:into-file=//options.html
+options.md
+```
+
+<!-- ```{=include=} appendix html:into-file=//nixos-options.html -->
+<!-- nixos-options.md -->
+<!-- ``` -->
+
+<!-- ```{=include=} appendix html:into-file=//nix-darwin-options.html -->
+<!-- nix-darwin-options.md -->
+<!-- ``` -->
--- a/docs/manual.xml
+++ b/docs/manual.xml
@ -1,71 +0,0 @@
-<!-- Copyright (c) 2019-2023, see AUTHORS. Licensed under MIT License, see LICENSE. -->
-<book xmlns="http://docbook.org/ns/docbook"
-      xmlns:xlink="http://www.w3.org/1999/xlink"
-      xmlns:xi="http://www.w3.org/2001/XInclude"
-      version="5.0"
-      xml:id="book-manual">
- <info>
-  <title>Self Host Blocks manual</title>
- </info>
- <preface>
-  <title>Preface</title>
-  <para>
-   Complete manual for Self Host Blocks, the building blocks for self-hosting with battery included.
-  </para>
-  <para>
-   If you encounter problems or bugs then please report them on the
-   <link xlink:href="https://github.com/ibizaman/selfhostblocks/issues">issue tracker</link>.
-  </para>
- </preface>
-
- <appendix xml:id="ch-options">
-  <title>Self Host Blocks configuration options</title>
-  <section xml:id="sec-usage">
-   <title>Usage</title>
-
-   <!--
-   Tags:
-   <title>
-   <section xml:id="sec-NAME">
-   <para>
-   <filename>
-   <replaceable>
-   <varname>
-   <programlisting language="nix">
-   -->
-
-   <para>
-    To use these options, import Self Host Blocks as a flake input, then import the default module for your system.
-<programlisting language="nix">
-{
-  inputs = {
-    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
-    sops-nix.url = "github:Mic92/sops-nix";
-
-    shb.url = "github:ibizaman/selfhostblocks";
-    shb.inputs.nixpkgs.follows = "nixpkgs";
-    shb.inputs.sops-nix.follows = "sops-nix";
-  };
-
-  outputs = { self, nixpkgs, shb }: {
-
-    nixosConfigurations.machine = nixpkgs.lib.nixosSystem {
-      system = "x86_64-linux";
-      modules = [
-        shb.nixosModules.x86_64-linux.default
-        ./machine.nix
-      ];
-    };
-
-  };
-}
-</programlisting>
-   </para>
-  </section>
-  <section xml:id="sec-options">
-   <title>Options</title>
-
-   <xi:include href="./nmd-result/selfhostblocks-options.xml" />
-  </section>
- </appendix>
-</book>
--- a/docs/options.md
+++ b/docs/options.md
@ -0,0 +1,7 @@
+# Self Host Blocks Options {#ch-options}
+
+```{=include=} options
+id-prefix: opt-
+list-id: selfhostblock-options
+source: @OPTIONS_JSON@
+```
--- a/docs/preface.md
+++ b/docs/preface.md
@ -0,0 +1,10 @@
+# Preface {#preface}
+
+This document is the complete manual for Self Host Blocks, the building blocks for self-hosting with battery included.
+
+Self Host Blocks is hosted on [GitHub](https://github.com/ibizaman/selfhostblocks). If you encounter
+problems or bugs then please report them on the [issue
+tracker](https://github.com/ibizaman/selfhostblocks/issues).
+
+Feel free to join the dedicated Matrix room
+[matrix.org#selfhostblocks](https://matrix.to/#/#selfhostblocks:matrix.org).
--- a/flake.lock
+++ b/flake.lock
@ -35,11 +35,11 @@
    },
    "nixpkgs": {
      "locked": {
-        "lastModified": 1687412861,
-        "narHash": "sha256-Z/g0wbL68C+mSGerYS2quv9FXQ1RRP082cAC0Bh4vcs=",
+        "lastModified": 1701253981,
+        "narHash": "sha256-ztaDIyZ7HrTAfEEUt9AtTDNoCYxUdSd6NrRHaYOIxtk=",
        "owner": "nixos",
        "repo": "nixpkgs",
-        "rev": "e603dc5f061ca1d8a19b3ede6a8cf9c9fcba6cdc",
+        "rev": "e92039b55bcd58469325ded85d4f58dd5a4eaf58",
        "type": "github"
      },
      "original": {
@ -51,11 +51,11 @@
    },
    "nixpkgs-stable": {
      "locked": {
-        "lastModified": 1687031877,
-        "narHash": "sha256-yMFcVeI+kZ6KD2QBrFPNsvBrLq2Gt//D0baHByMrjFY=",
+        "lastModified": 1700905716,
+        "narHash": "sha256-w1vHn2MbGfdC+CrP3xLZ3scsI06N0iQLU7eTHIVEFGw=",
        "owner": "NixOS",
        "repo": "nixpkgs",
-        "rev": "e2e2059d19668dab1744301b8b0e821e3aae9c99",
+        "rev": "dfb95385d21475da10b63da74ae96d89ab352431",
        "type": "github"
      },
      "original": {
@ -67,11 +67,11 @@
    },
    "nixpkgs_2": {
      "locked": {
-        "lastModified": 1686979235,
-        "narHash": "sha256-gBlBtk+KrezFkfMrZw6uwTuA7YWtbFciiS14mEoTCo0=",
+        "lastModified": 1700856099,
+        "narHash": "sha256-RnEA7iJ36Ay9jI0WwP+/y4zjEhmeN6Cjs9VOFBH7eVQ=",
        "owner": "NixOS",
        "repo": "nixpkgs",
-        "rev": "7cc30fd5372ddafb3373c318507d9932bd74aafe",
+        "rev": "0bd59c54ef06bc34eca01e37d689f5e46b3fe2f1",
        "type": "github"
      },
      "original": {
@ -84,11 +84,11 @@
    "nmdsrc": {
      "flake": false,
      "locked": {
-        "lastModified": 1687627428,
-        "narHash": "sha256-7zGfXuNS5RHqhpEdz2fwrtqvF86JRo5U1hrxZSYgcm8=",
+        "lastModified": 1701431551,
+        "narHash": "sha256-5HPHG1u3koaWHG/TXHl5/YxYPYOuKc58104btrD8ypE=",
        "ref": "refs/heads/master",
-        "rev": "824a380546b5d0d0eb701ff8cd5dbafb360750ff",
-        "revCount": 63,
+        "rev": "f18defadcc25e69e95b04493ee02682005472255",
+        "revCount": 65,
        "type": "git",
        "url": "https://git.sr.ht/~rycee/nmd"
      },
@ -112,11 +112,11 @@
        "nixpkgs-stable": "nixpkgs-stable"
      },
      "locked": {
-        "lastModified": 1687398569,
-        "narHash": "sha256-e/umuIKFcFtZtWeX369Hbdt9r+GQ48moDmlTcyHWL28=",
+        "lastModified": 1701127353,
+        "narHash": "sha256-qVNX0wOl0b7+I35aRu78xUphOyELh+mtUp1KBx89K1Q=",
        "owner": "Mic92",
        "repo": "sops-nix",
-        "rev": "2ff6973350682f8d16371f8c071a304b8067f192",
+        "rev": "b1edbf5c0464b4cced90a3ba6f999e671f0af631",
        "type": "github"
      },
      "original": {
--- a/flake.nix
+++ b/flake.nix
@ -14,11 +14,44 @@

  outputs = { nixpkgs, nix-flake-tests, flake-utils, nmdsrc, ... }: flake-utils.lib.eachDefaultSystem (system:
    let
-      pkgs = import nixpkgs {
-        inherit system;
+      patches = [
+        ''
+        From a4d67df38628eaa3e1823af7b7613af3d7ff7555 Mon Sep 17 00:00:00 2001
+        From: ibizaman <ibizapeanut@gmail.com>
+        Date: Sun, 3 Dec 2023 21:09:30 -0800
+        Subject: [PATCH] fix for nixos-render-docs media path
+        
+        ---
+         .../tools/nix/nixos-render-docs/src/nixos_render_docs/manual.py | 2 +-
+         1 file changed, 1 insertion(+), 1 deletion(-)
+        
+        diff --git a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manual.py b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manual.py
+        index d605dd88b37d..3482cc02c4d1 100644
+        --- a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manual.py
+        +++ b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manual.py
+        @@ -506,7 +506,7 @@ class ManualHTMLRenderer(RendererMixin, HTMLRenderer):
+                 in_dir = self._in_dir
+                 for included, path in fragments:
+                     try:
+        -                self._in_dir = (in_dir / path).parent
+        +                self._in_dir = path.parent
+                         inner.append(self.render(included))
+                     except Exception as e:
+                         raise RuntimeError(f"rendering {path}") from e
+        -- 
+        2.42.0
+        ''
+      ];
+      originPkgs = nixpkgs.legacyPackages.${system};
+      patchedNixpkgs = originPkgs.applyPatches {
+        name = "nixpkgs-patched";
+        src = nixpkgs;
+        patches = map (p: originPkgs.writeText "patch" p) patches;
      };

-      nmd = import nmdsrc { inherit pkgs; };
+      pkgs = import patchedNixpkgs {
+        inherit system;
+      };

      allModules = [
        modules/blocks/authelia.nix
@ -46,36 +79,10 @@
          imports = allModules;
        };

-        # Inspiration from https://github.com/nix-community/nix-on-droid/blob/039379abeee67144d4094d80bbdaf183fb2eabe5/docs/default.nix#L22
-        packages.manualHtml = let
-          setupModule = {
-            _module.args.pkgs = pkgs.lib.mkForce (nmd.scrubDerivations "pkgs" pkgs);
-            _module.check = false;
-          };
-
-          modulesDocs = nmd.buildModulesDocs {
-            modules = allModules ++ [ setupModule ];
-            moduleRootPaths = [ ./. ];
-            mkModuleUrl = path: "https://github.com/ibizaman/selfhostblocks/blob/main/${path}";
-            channelName = "selfhostblocks";
-            docBook = { id = "selfhostblocks-options"; optionIdPrefix = "shb-opt"; };
-          };
-
-          manual = nmd.buildDocBookDocs {
-            pathName = "selfhostblocks";
-            modulesDocs = [ modulesDocs ];
-            documentsDirectory = ./docs;
-            chunkToc = ''
-              <toc>
-                <d:tocentry xmlns:d="http://docbook.org/ns/docbook" linkend="book-manual">
-                  <?dbhtml filename="index.html"?>
-                  <d:tocentry linkend="ch-options"><?dbhtml filename="selfhostblocks-options.html"?></d:tocentry>
-                </d:tocentry>
-              </toc>
-            '';
-          };
-        in
-          manual.html;
+        packages.manualHtml = pkgs.callPackage ./docs {
+          inherit allModules nmdsrc;
+          release = "0.0.1";
+        };

        checks =
          let