docs: drop options.md from the repository

Generate the file on the readthedocs builder using Nix. Since there is
no root access or user namespaces, we have to use proot (see
https://nixos.wiki/wiki/Nix_Installation_Guide#PRoot).

.readthedocs.yaml

@@ -8,6 +8,14 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3"
+  apt_packages:
+    - nix
+    - proot
+  jobs:
+    pre_install:
+      - mkdir -p ~/.nix ~/.config/nix
+      - echo "experimental-features = nix-command flakes" > ~/.config/nix/nix.conf
+      - proot -b ~/.nix:/nix /bin/sh -c "nix build -L .#optionsDoc && cp -v result docs/options.md"
 
 sphinx:
    configuration: docs/conf.py

docs/howto-develop.rst

@@ -10,7 +10,7 @@ Run NixOS tests
 ---------------
 
 To run the test suite, you need to enable `Nix Flakes
-<https://nixos.wiki/wiki/Flakes#Installing_flakes>`.
+<https://nixos.wiki/wiki/Flakes#Installing_flakes>`_.
 
 You can then run the testsuite via
 
@@ -30,28 +30,20 @@ run tests manually. For instance:
 Contributing to the documentation
 ---------------------------------
 
-The documentation is written in RST (except option documentation which is in MarkDown),
+The documentation is written in RST (except option documentation which is in CommonMark),
 built with Sphinx and published by `Read the Docs <https://readthedocs.org/>`_.
 
-For the syntax, see `RST/Sphinx Cheatsheet
-<https://sphinx-tutorial.readthedocs.io/cheatsheet/>`_.
+For the syntax, see the `RST/Sphinx primer
+<https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_.
+
+To build the documentation, you need to enable `Nix Flakes
+<https://nixos.wiki/wiki/Flakes#Installing_flakes>`_.
 
-The ``shell.nix`` provides all the tooling required to build the
-documentation:
 
 ::
 
-   $ nix-shell
-   $ cd docs
-   $ make html
-   $ firefox ./_build/html/index.html
-
-Note if you modify some NixOS mailserver options, you would also need
-to regenerate the ``options.md`` file:
-
-::
-
-   $ nix-shell --run generate-options
+   $ nix build .#documentation
+   $ xdg-open result/index.html
 
 Nixops
 ------

flake.nix

@@ -81,22 +81,6 @@
       python ${./scripts/generate-options.py} ${options} > $out
     '';
 
-    # This is a script helping users to generate this file in the docs directory
-    generateOptions = pkgs.writeShellScriptBin "generate-options" ''
-      install -vm644 ${optionsDoc} ./docs/options.md
-    '';
-
-    # This is to ensure we don't forget to update the options.md file
-    testOptions = pkgs.runCommand "test-options" {} ''
-      if ! diff -q ${./docs/options.md} ${optionsDoc}
-      then
-        echo "The file ./docs/options.md is not up-to-date and needs to be regenerated!"
-        echo "  hint: run 'nix-shell --run generate-options' to generate this file"
-        exit 1
-      fi
-      echo "test: ok" > $out
-    '';
-
     documentation = pkgs.stdenv.mkDerivation {
       name = "documentation";
       src = lib.sourceByRegex ./docs ["logo\\.png" "conf\\.py" "Makefile" ".*\\.rst"];
@@ -125,14 +109,15 @@
     };
     nixosModule = self.nixosModules.default; # compatibility
     hydraJobs.${system} = allTests // {
-      test-options = testOptions;
       inherit documentation;
     };
     checks.${system} = allTests;
+    packages.${system} = {
+      inherit optionsDoc documentation;
+    };
     devShells.${system}.default = pkgs.mkShell {
       inputsFrom = [ documentation ];
       packages = with pkgs; [
-        generateOptions
         clamav
       ];
     };