doc(manuals): organize content

.version

@@ -0,0 +1 @@
+26.05

default.nix

@@ -14,9 +14,6 @@
   lib ? import "${sources.nixpkgs}/lib",
 }:
 let
-  version = "26.05";
-  revision = flake.sourceInfo.shortRev or flake.sourceInfo.dirtyShortRev;
-
   devLib = import ./pkgs/lib.nix { inherit lib sources system; };
 
   flakeAttrs = default.import ./maintainers/flake { };
@@ -60,7 +57,8 @@ let
     };
 
     manuals = self.call manuals/default.nix {
-      inherit revision version;
+      version = lib.readFile ./.version;
+      revision = flake.sourceInfo.shortRev or flake.sourceInfo.dirtyShortRev;
       modulesPath = "${sources.nixpkgs}/nixos/modules";
     };
 

maintainers/flake/default.nix

@@ -36,28 +36,31 @@ in
 
   # depends on the system (e.g. packages.x86_64-linux)
   perSystem = rec {
-    packages = nonBrokenPackages // {
-      inherit (default) manuals overview;
+    packages =
+      nonBrokenPackages
+      // {
+        inherit (default) overview;
 
-      # Combined overview and html manual
-      overview-with-manual = pkgs.runCommand "overview-with-manual" { } ''
-        mkdir -p $out
-        cp -r ${default.overview}/* $out/
-        mkdir -p $out/manual
-        cp -r ${default.manuals.html}/* $out/manual/
-      '';
+        # Combined overview and HTML manuals
+        overview-with-manuals = pkgs.runCommand "overview-with-manuals" { } ''
+          mkdir -p $out
+          cp -r ${default.overview}/* $out/
+          mkdir -p $out/manuals
+          cp -r ${default.manuals.html}/* $out/manuals/
+        '';
 
-      # Configuration options in JSON
-      options =
-        pkgs.runCommand "options.json"
-          {
-            build = default.optionsDoc.optionsJSON;
-          }
-          ''
-            mkdir $out
-            cp $build/share/doc/nixos/options.json $out/
-          '';
-    };
+        # Configuration options in JSON
+        options =
+          pkgs.runCommand "options.json"
+            {
+              build = default.optionsDoc.optionsJSON;
+            }
+            ''
+              mkdir $out
+              cp $build/share/doc/nixos/options.json $out/
+            '';
+      }
+      // flattenFlakeAttrs { inherit (default) manuals; };
 
     checks = default.import ./checks.nix { inherit nonBrokenPackages; };
 

manuals/Contributor.md

@@ -3,4 +3,14 @@
 - Version: @NGIPKGS_VERSION@
 - Revision: @NGIPKGS_REVISION@
 
-ToDo
+```{toctree}
+Contributor/How_to/use/NGIpkgs_Contributor_s_Manual.md
+```
+
+```{toctree}
+Contributor/Exercise_to.md
+Contributor/How_to.md
+Contributor/Why_to.md
+Contributor/What_is.md
+Contributor/Release.md
+```

manuals/Contributor/Exercise_to.md

@@ -0,0 +1,5 @@
+{#Contributor_Exercise_to}
+# Tutorials for contributors
+
+While tutorials on Nix in general belong to [nix.dev/tutorials](https://nix.dev/tutorials/),
+the following exercises cover complementary topics arising while crafting NGIpkgs.

manuals/Contributor/How_to.md

@@ -0,0 +1,20 @@
+{#Contributor_How_to}
+# Recipes for contributors
+
+While generic how-to guides on Nix belong to [nix.dev/guides](https://nix.dev/guides/),
+the following recipes cover complementary topics arising while crafting NGIpkgs.
+
+```{toctree}
+How_to/assist.md
+How_to/develop.md
+How_to/document.md
+How_to/learn.md
+How_to/maintain.md
+How_to/optimize.md
+How_to/reuse.md
+How_to/review.md
+How_to/scale.md
+How_to/secure.md
+How_to/update.md
+How_to/use.md
+```

manuals/Contributor/How_to/assist.md

@@ -0,0 +1,6 @@
+{#Contributor_How_to_assist}
+# How to assist?
+
+```{toctree}
+assist/usability.md
+```

manuals/Contributor/How_to/assist/usability.md

@@ -0,0 +1,6 @@
+{#Contributor_How_to_assist_usability}
+# How to assist usability?
+
+```{toctree}
+usability/of_a_service.md
+```

manuals/Contributor/How_to/assist/usability/of_a_service.md

@@ -0,0 +1,40 @@
+{#Contributor_How_to_assist_usability_of_a_service}
+# How to assist usability of a service?
+
+As expected by [How to install a service](#User_How_to_install_a_service),
+a service can provide convenient opt-in options
+to configure its integration into other services (a database, a cache, a reverse-proxy, a mail-server, …)
+to assist users not necessarily knowing how to configure those integrations.
+
+Such convenient options usually cannot and should not handle all possible integrations,
+just a sensible integration providing the user with an easy way
+to configure services running on the same host.
+
+When enabled, a sensible integration :
+- configures its integration;
+- enables the dependent service using `lib.mkDefault`;
+- does not add `assertions` that the dependent services are enabled;
+- assumes that the dependent service runs on the same host;
+- when possible, integrates without claiming any unique shared resources
+  (eg. uses a Unix socket in the runtime directory of the service
+  instead of binding to a TCP or UDP port on the loopback interface).
+
+Users fancying an alternative integration
+could just not opt-in and instead configure their own integration.
+Examples of those alternative integrations can be provided
+as examples imported in both:
+- the service's documentation,
+- the service's `passthru.tests` and/or `nixosTests`.
+
+<!--
+ToDo: [NixOS RFC 189](https://github.com/ibizaman/rfcs/blob/contracts/rfcs/0189-contracts.md)
+is a relevant draft aiming to assist usability of services.
+-->
+
+```{toctree}
+of_a_service/using_Caddy.md
+of_a_service/using_Nginx.md
+of_a_service/using_Postfix.md
+of_a_service/using_PostgreSQL.md
+of_a_service/using_Redis.md
+```

manuals/Contributor/How_to/assist/usability/of_a_service/using_Caddy.md

@@ -0,0 +1,4 @@
+{#Contributor_How_to_assist_usability_of_a_service_using_Caddy}
+# How to assist usability of a service using Caddy?
+
+ToDo

manuals/Contributor/How_to/assist/usability/of_a_service/using_Nginx.md

@@ -0,0 +1,66 @@
+{#Contributor_How_to_assist_usability_of_a_service_using_Nginx}
+# How to assist usability of a service using Nginx?
+
+A service can provide a convenient opt-in option
+to integrate a virtual-host in `services.nginx`, acting as a reverse-proxy:
+
+```nix
+{ pkgs, config, lib, modulesPath, ...}:
+{
+  options.services.${service} = {
+    enable = lib.mkEnableOption "an Nginx reverse-proxy to ${service}";
+    virtualHost = lib.mkOption {
+      description = ''
+        With this option, you can customize the nginx virtual host which already has sensible defaults for `${service}`.
+        By default, the {option}`serverName` is
+        `${service}.''${config.networking.domain}`,
+        TLS is active, and certificates are acquired via ACME.
+      '';
+      default = {};
+      example = lib.literalExpression ''
+        {
+          enableACME = false;
+          useACMEHost = config.networking.domain;
+        }
+      '';
+      type =
+        lib.types.submodule (
+          lib.recursiveUpdate
+            (import (modulesPath + "/services/web-servers/nginx/vhost-options.nix") {
+              inherit config lib;
+            })
+            {
+              options.serverName = {
+                default = "${service}.${config.networking.domain}";
+                defaultText = "${service}.\${config.networking.domain}";
+              };
+            }
+        );
+    };
+  };
+  config = lib.mkIf cfg.enable (
+    lib.mkMerge [
+      (lib.mkIf cfg.nginx.enable {
+        services.nginx = {
+          enable = lib.mkDefault true;
+          virtualHosts.${cfg.nginx.serverName} = lib.mkMerge [
+            cfg.nginx.virtualHost
+            {
+              forceSSL = lib.mkDefault true;
+              enableACME = lib.mkDefault true;
+              locations."/" = {
+                proxyPass = "http://unix:/run/${service}/socket";
+                recommendedProxySettings = true;
+                proxyWebsockets = true;
+              };
+            }
+          ];
+        };
+        systemd.services.nginx.serviceConfig.SupplementaryGroups = [
+          config.users.groups.${service}.name
+        ];
+      })
+    ]
+  );
+}
+```

manuals/Contributor/How_to/assist/usability/of_a_service/using_Postfix.md

@@ -0,0 +1,4 @@
+{#Contributor_How_to_assist_usability_of_a_service_using_Postfix}
+# How to assist usability of a service using Postfix?
+
+ToDo

manuals/Contributor/How_to/assist/usability/of_a_service/using_PostgreSQL.md

@@ -0,0 +1,7 @@
+{#Contributor_How_to_assist_usability_of_a_service_using_PostgreSQL}
+# How to assist usability of a service using PostgreSQL?
+
+A service can provide a convenient opt-in option
+to integrate a database in `services.postgresql`:
+
+ToDo

manuals/Contributor/How_to/assist/usability/of_a_service/using_Redis.md

@@ -0,0 +1,4 @@
+{#Contributor_How_to_assist_usability_of_a_service_using_Redis}
+# How to assist usability of a service using Redis?
+
+ToDo

manuals/Contributor/How_to/develop.md

@@ -0,0 +1,7 @@
+{#Contributor_How_to_develop}
+# How to develop?
+
+```{toctree}
+develop/a_package.md
+develop/a_service.md
+```

manuals/Contributor/How_to/develop/a_package.md

@@ -0,0 +1,7 @@
+{#Contributor_How_to_develop_a_package}
+# How to develop a package?
+
+```{toctree}
+a_package/using_Elixir.md
+a_package/using_CAcert.md
+```

manuals/Contributor/How_to/develop/a_package/using_CAcert.md

@@ -0,0 +1,17 @@
+{#Contributor_How_to_develop_a_package_using_CAcert}
+# How to develop a package using CAcert?
+
+Some packages, especially those to update other packages,
+may need to access resources over TLS outside the usual `fetch*` utilities.
+To be used TLS requires to specify a pool of certificate authorities (CA),
+those usually come from `pkgs.cacert`, and can provisionned like this:
+```nix
+{ stdenv, cacert }:
+stdenv.mkDerivation {
+  nativeBuildInputs = [ cacert ];
+  preConfigure = ''
+    export GIT_SSL_CAINFO=$NIX_SSL_CERT_FILE
+    export SSL_CERT_FILE=$NIX_SSL_CERT_FILE
+  '';
+};
+```

manuals/Contributor/How_to/develop/a_package/using_Elixir.md

@@ -0,0 +1,7 @@
+{#Contributor_How_to_develop_a_package_using_Elixir}
+# How to develop a package using Elixir?
+
+```{toctree}
+using_Elixir/and_Surface.md
+using_Elixir/with_deps_nix.md
+```

manuals/Contributor/How_to/develop/a_package/using_Elixir/and_Surface.md

@@ -0,0 +1,37 @@
+{#Contributor_How_to_develop_a_package_using_Elixir_and_Surface}
+# How to develop a package using Elixir and Surface?
+
+Using [Surface UI](https://github.com/surface-ui/surface)
+requires to build the Elixir dependencies into "$out"
+and to keep the paths into the built artifacts.
+
+This can be done by overriding the `buildMix` used to build all dependencies:
+```nix
+let
+  beamPackages = beam.packages // {
+    buildMix =
+      previousArgs:
+      beamPkgs.buildMix (
+        lib.recursiveUpdate previousArgs {
+          erlangDeterministicBuilds = false;
+          postUnpack = previousArgs.postUnpack or "" + ''
+            mkdir -p $out
+            mv $sourceRoot $out/src
+            sourceRoot=$out/src
+            src=$(mktemp -d)
+          '';
+          postInstall = previousArgs.postInstall or "" + ''
+            src=$out/src
+            rm -rf _build
+          '';
+        }
+      );
+  };
+in
+beamPackages.mixRelease {
+  inherit (beamPackages) erlang elixir;
+  mixNixDeps = import ./deps.nix {
+    inherit lib g beamPackages;
+  };
+}
+```