Merge pull request NotAShelf#187 from NotAShelf/markdown-docs

docs: refactor

docs/default.nix

@@ -2,6 +2,7 @@
   pkgs,
   lib ? import ../lib/stdlib-extended.nix pkgs.lib,
   nmdSrc,
+  ...
 }: let
   nmd = import nmdSrc {
     inherit lib;
@@ -29,103 +30,109 @@
     ];
   };
 
+  dontCheckDefinitions = {_module.check = false;};
+
   githubDeclaration = user: repo: subpath: let
     urlRef = "main";
   in {
     url = "https://github.com/${user}/${repo}/blob/${urlRef}/${subpath}";
     name = "<${repo}/${subpath}>";
   };
 
-  dontCheckDefinitions = {_module.check = false;};
-
   nvimPath = toString ./..;
 
   buildOptionsDocs = args @ {
     modules,
-    includeModuleSystemsOptions ? true,
+    includeModuleSystemOptions ? true,
     ...
   }: let
-    options = (lib.evalModules {inherit modules;}).options;
+    inherit ((lib.evalModules {inherit modules;})) options;
   in
-    pkgs.buildPackages.nixosOptionsDoc
-    ({
+    pkgs.buildPackages.nixosOptionsDoc ({
         options =
-          if includeModuleSystemsOptions
+          if includeModuleSystemOptions
           then options
-          else builtins.removeAttrs (options ["_module"]);
+          else builtins.removeAttrs options ["_module"];
         transformOptions = opt:
           opt
           // {
-            # Clean up declaration sites to not refer to local source tree
-            declarations =
-              map
-              (decl:
-                if lib.hasPrefix nvimPath (toString decl)
-                then
-                  githubDeclaration "notashelf" "neovim-flake"
-                  (lib.removePrefix "/" (lib.removePrefix nvimPath (toString decl)))
-                else decl)
-              opt.declarations;
+            # Clean up declaration sites to not refer to the Home Manager
+            # source tree.
+            declarations = map (decl:
+              if lib.hasPrefix nvimPath (toString decl)
+              then
+                githubDeclaration "notashelf" "neovim-flake"
+                (lib.removePrefix "/" (lib.removePrefix nvimPath (toString decl)))
+              else if decl == "lib/modules.nix"
+              then
+                # TODO: handle this in a better way (may require upstream
+                # changes to nixpkgs)
+                githubDeclaration "NixOS" "nixpkgs" decl
+              else decl)
+            opt.declarations;
           };
       }
-      // builtins.removeAttrs args ["modules" "includeModuleSystemsOptions"]);
+      // builtins.removeAttrs args ["modules" "includeModuleSystemOptions"]);
 
   nvimModuleDocs = buildOptionsDocs {
     modules =
-      import ../modules/modules.nix
-      {
-        inherit pkgs lib;
+      import ../modules/modules.nix {
+        inherit lib pkgs;
         check = false;
       }
       ++ [scrubbedPkgsModule];
     variablelistId = "neovim-flake-options";
   };
 
-  docs = nmd.buildDocBookDocs {
-    pathName = "neovim-flake";
-    projectName = "neovim-flake";
-    modulesDocs = [
-      {
-        docBook = pkgs.linkFarm "nvim-module-docs-for-nmd" {
-          "nmd-result/neovim-flake-options.xml" = nvimModuleDocs.optionsDocBook;
-        };
-      }
-    ];
-    documentsDirectory = ./.;
-    documentType = "book";
-    chunkToc = ''
-      <toc>
-        <d:tocentry xmlns:d="http://docbook.org/ns/docbook" linkend="book-neovim-flake-manual">
-          <?dbhtml filename="index.html"?>
-          <d:tocentry linkend="ch-options">
-            <?dbhtml filename="options.html"?>
-          </d:tocentry>
-          <d:tocentry linkend="ch-release-notes">
-            <?dbhtml filename="release-notes.html"?>
-          </d:tocentry>
-        </d:tocentry>
-      </toc>
+  release-config = builtins.fromJSON (builtins.readFile ../release.json);
+  revision = "release-${release-config.release}";
+  # Generate the `man home-configuration.nix` package
+  nvf-configuration-manual =
+    pkgs.runCommand "neovim-flake-reference-manpage" {
+      nativeBuildInputs = [pkgs.buildPackages.installShellFiles pkgs.nixos-render-docs];
+      allowedReferences = ["out"];
+    } ''
+      # Generate manpages.
+      mkdir -p $out/share/man/man5
+      mkdir -p $out/share/man/man1
+      nixos-render-docs -j $NIX_BUILD_CORES options manpage \
+        --revision ${revision} \
+        ${nvimModuleDocs.optionsJSON}/share/doc/nixos/options.json \
+        $out/share/man/man5/neovim-flake.5
+      cp ${./neovim-flake.1} $out/share/man/man1/neovim-flake.1
     '';
+  # Generate the HTML manual pages
+  neovim-flake-manual = pkgs.callPackage ./manual.nix {
+    inherit revision;
+    outputPath = "share/doc/neovim-flake";
+    nmd = nmdSrc;
+    options = {
+      neovim-flake = nvimModuleDocs.optionsJSON;
+    };
   };
+  html = neovim-flake-manual;
+  htmlOpenTool = pkgs.callPackage ./html-open-tool.nix {} {inherit html;};
 in {
-  options.json =
-    pkgs.runCommand "options.json"
-    # TODO: Use `nvimOptionsDoc.optionsJSON` directly once upstream
-    # `nixosOptionsDoc` is more customizable
-    {
-      meta.description = "List of neovim-flake options in JSON format";
-    } ''
-      mkdir -p $out/{share/doc,nix-support}
-      cp -a ${nvimModuleDocs.optionsJSON}/share/doc/nixos $out/share/doc/neovim-flake
-      substitute \
-       ${nvimModuleDocs.optionsJSON}/nix-support/hydra-build-products \
-       $out/nix-support/hydra-build-products \
-       --replace \
-        '${nvimModuleDocs.optionsJSON}/share/doc/nixos' \
-        "$out/share/doc/neovim-flake"
-    '';
+  inherit nmdSrc;
 
-  inherit (docs) manPages;
+  options = {
+    # TODO: Use `hmOptionsDocs.optionsJSON` directly once upstream
+    # `nixosOptionsDoc` is more customizable.
+    json =
+      pkgs.runCommand "options.json" {
+        meta.description = "List of Home Manager options in JSON format";
+      } ''
+        mkdir -p $out/{share/doc,nix-support}
+        cp -a ${nvimModuleDocs.optionsJSON}/share/doc/nixos $out/share/doc/neovim-flake
+        substitute \
+          ${nvimModuleDocs.optionsJSON}/nix-support/hydra-build-products \
+          $out/nix-support/hydra-build-products \
+          --replace \
+            '${nvimModuleDocs.optionsJSON}/share/doc/nixos' \
+            "$out/share/doc/neovim-flake"
+      '';
+  };
 
-  manual = {inherit (docs) html htmlOpenTool;};
+  manPages = nvf-configuration-manual;
+  manual = {inherit html htmlOpenTool;};
 }

docs/footer.5

@@ -0,0 +1,3 @@
+.SH "AUTHORS"
+.PP
+neovim-flake contributors

docs/header.5

@@ -0,0 +1,14 @@
+.TH "neovim-flake" "5" "01/01/1980" "neovim-flake"
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" enable line breaks after slashes
+.cflags 4 /
+.SH "NAME"
+neovim-flake configuration specification
+.SH "OPTIONS"
+.PP
+You can use the following options in
+home\-configuration\&.nix:
+.PP

docs/highlight-style.css

@@ -0,0 +1,8 @@
+pre {
+	padding: 0;
+}
+
+pre code.hljs {
+	border: none;
+	margin: 0;
+}

docs/html-open-tool.nix

@@ -0,0 +1,43 @@
+{
+  writeShellScriptBin,
+  makeDesktopItem,
+  symlinkJoin,
+}: {
+  html,
+  pathName ? "neovim-flake",
+  projectName ? pathName,
+  name ? "${pathName}-help",
+}: let
+  helpScript = writeShellScriptBin name ''
+    set -euo pipefail
+
+    if [[ ! -v BROWSER || -z $BROWSER ]]; then
+      for candidate in xdg-open open w3m; do
+        BROWSER="$(type -P $candidate || true)"
+        if [[ -x $BROWSER ]]; then
+          break;
+        fi
+      done
+    fi
+
+    if [[ ! -v BROWSER || -z $BROWSER ]]; then
+      echo "$0: unable to start a web browser; please set \$BROWSER"
+      exit 1
+    else
+      exec "$BROWSER" "${html}/share/doc/${pathName}/index.xhtml"
+    fi
+  '';
+
+  desktopItem = makeDesktopItem {
+    name = "${pathName}-manual";
+    desktopName = "${projectName} Manual";
+    genericName = "View ${projectName} documentation in a web browser";
+    icon = "nix-snowflake";
+    exec = "${helpScript}/bin/${name}";
+    categories = ["System"];
+  };
+in
+  symlinkJoin {
+    inherit name;
+    paths = [helpScript desktopItem];
+  }

docs/manual.nix

@@ -0,0 +1,64 @@
+{
+  stdenv,
+  lib,
+  documentation-highlighter,
+  nmd,
+  revision,
+  outputPath ? "share/doc/neovim-flake",
+  options,
+  nixos-render-docs,
+}:
+stdenv.mkDerivation {
+  name = "neovim-flake-manual";
+
+  nativeBuildInputs = [nixos-render-docs];
+
+  src = ./manual;
+
+  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@' \
+        ${options.neovim-flake}/share/doc/nixos/options.json
+
+    substituteInPlace ./manual.md \
+      --replace \
+        '@VERSION@' \
+        ${revision}
+
+    cp ${nmd}/static/style.css out/style.css
+    cp -t out/highlightjs ${nmd}/static/highlightjs/tomorrow-night.min.css
+    cp ${./highlight-style.css} out/highlightjs/highlight-style.css
+
+    nixos-render-docs manual html \
+      --manpage-urls ./manpage-urls.json \
+      --revision ${lib.trivial.revisionWithDefault revision} \
+      --stylesheet style.css \
+      --stylesheet highlightjs/tomorrow-night.min.css \
+      --stylesheet highlightjs/highlight-style.css \
+      --script highlightjs/highlight.pack.js \
+      --script highlightjs/loader.js \
+      --toc-depth 1 \
+      --section-toc-depth 1 \
+      manual.md \
+      out/index.xhtml
+  '';
+
+  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
+  '';
+}