nixpkgs manual in CommonMark using sphinx+myst and jupyter-book

doc-md/.gitignore

@@ -0,0 +1 @@
+_build

doc-md/_config.yml

@@ -0,0 +1,28 @@
+# Book settings
+# Learn more at https://jupyterbook.org/customize/config.html
+
+title: "Nixpkgs Manual"
+author: "Nixpkgs contributors"
+logo: logo.svg
+
+# Force re-execution of notebooks on each build.
+# See https://jupyterbook.org/content/execute.html
+execute:
+  execute_notebooks: "off"
+
+# Define the name of the latex output file for PDF builds
+latex:
+  latex_documents:
+    targetname: book.tex
+
+# Information about where the book exists on the web
+repository:
+  url: https://github.com/NixOS/nixpkgs  # Online location of your book
+  path_to_book: doc-md  # Optional path to your book, relative to the repository root
+  branch: master  # Which branch of the repository should be used when creating links (optional)
+
+# Add GitHub buttons to your book
+# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
+html:
+  use_issues_button: true
+  use_repository_button: true

doc-md/default.nix

@@ -0,0 +1,94 @@
+{ pkgs ? (import ./.. { })
+}:
+
+with pkgs;
+
+let
+  toc = import ./toc.nix;
+
+  # Some files get included in the build directory, but are
+  # only needed when doing the old docbook build.
+  unusedFiles = [
+    "doc-support/parameters.xml"
+    "manual.xml"
+    "release-notes.xml" # Not used at all, should be removed
+  ];
+
+  # Take the source tree from the old docs, convert everything to .md
+  # Temporary solution.
+  mdInput = stdenv.mkDerivation {
+    name = "nixpkgs-manual-md-input";
+    src = ../doc;
+    nativeBuildInputs = [
+      pandoc
+    ];
+
+    buildPhase = ''
+      for file in "${lib.concatStringsSep " " unusedFiles}"; do
+        echo "Removing $file"
+        rm $file
+      done
+    '';
+
+    installPhase = ''
+      mkdir -p $out
+      # Convert Docbook to CommonMark
+      for file in `find . -name "*.xml"`; do
+        newfile="$out/''${file%.*}.md"
+        echo "Converting $file to $newfile"
+        mkdir -p "$out/$(dirname $file)"
+        pandoc --from docbook --to commonmark "$file" -o "$newfile"
+      done
+      # Copy existing CommonMark files
+      for file in `find . -name "*.md"`; do
+        bname="$(basename $file)"
+        # Remove section/chapter parts
+        newfile="$out/$(dirname $file)/''${bname%%.*}.md"
+        echo "Moving $file to $newfile"
+        mkdir -p "$out/$(dirname $file)"
+        cp "$file" "$newfile"
+      done
+    '';
+  };
+
+  logo = fetchurl {
+    url = "https://raw.githubusercontent.com/NixOS/nixos-homepage/053ef7b456d1333197b08bcb36700249d3291e55/logo/nixos-hex.svg";
+    sha256 = "RIsQdOGgtgX3EngW4g6r/yEcYaNd9j9PFYJNxK3B1R8=";
+  };
+
+  # Build the manual
+  manual = let
+    tocForManual = builtins.toFile "toc.json" (builtins.toJSON toc);
+  in callPackage (
+    { stdenv
+    , python3
+    }:
+
+    stdenv.mkDerivation {
+      name = "nixpkgs-manual";
+
+      src = ./.;
+
+      nativeBuildInputs = [
+        python3.pkgs.jupyter-book
+      ];
+
+      buildPhase = ''
+        ln -s ${mdInput} doc
+        cp ${tocForManual} _toc.yml
+        cp ${logo} logo.svg
+        jupyter-book build -n --keep-going .
+      '';
+
+      installPhase = ''
+        mkdir -p $out/share/doc/nixpkgs-manual
+        mv -T _build/html $out/share/doc/nixpkgs-manual
+      '';
+
+      passthru = {
+        inherit logo mdInput toc;
+      };
+    }
+  ) { };
+
+in manual