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).
This commit is contained in:
Naïm Favier 2022-12-01 14:22:27 +01:00
parent 4fcab839d7
commit 0bbb2ac74e
No known key found for this signature in database
GPG Key ID: 95AFCE8211908325
4 changed files with 20 additions and 1237 deletions

View File

@ -8,6 +8,14 @@ build:
os: ubuntu-22.04 os: ubuntu-22.04
tools: tools:
python: "3" 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: sphinx:
configuration: docs/conf.py configuration: docs/conf.py

View File

@ -10,7 +10,7 @@ Run NixOS tests
--------------- ---------------
To run the test suite, you need to enable `Nix Flakes 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 You can then run the testsuite via
@ -30,28 +30,20 @@ run tests manually. For instance:
Contributing to the documentation 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/>`_. built with Sphinx and published by `Read the Docs <https://readthedocs.org/>`_.
For the syntax, see `RST/Sphinx Cheatsheet For the syntax, see the `RST/Sphinx primer
<https://sphinx-tutorial.readthedocs.io/cheatsheet/>`_. <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 $ nix build .#documentation
$ cd docs $ xdg-open result/index.html
$ 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
Nixops Nixops
------ ------

File diff suppressed because it is too large Load Diff

View File

@ -81,22 +81,6 @@
python ${./scripts/generate-options.py} ${options} > $out 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 { documentation = pkgs.stdenv.mkDerivation {
name = "documentation"; name = "documentation";
src = lib.sourceByRegex ./docs ["logo\\.png" "conf\\.py" "Makefile" ".*\\.rst"]; src = lib.sourceByRegex ./docs ["logo\\.png" "conf\\.py" "Makefile" ".*\\.rst"];
@ -125,14 +109,15 @@
}; };
nixosModule = self.nixosModules.default; # compatibility nixosModule = self.nixosModules.default; # compatibility
hydraJobs.${system} = allTests // { hydraJobs.${system} = allTests // {
test-options = testOptions;
inherit documentation; inherit documentation;
}; };
checks.${system} = allTests; checks.${system} = allTests;
packages.${system} = {
inherit optionsDoc documentation;
};
devShells.${system}.default = pkgs.mkShell { devShells.${system}.default = pkgs.mkShell {
inputsFrom = [ documentation ]; inputsFrom = [ documentation ];
packages = with pkgs; [ packages = with pkgs; [
generateOptions
clamav clamav
]; ];
}; };