nixos/sourcehut: convert manual chapter to MD

3 files changed, 160 insertions, 73 deletions

diff --git a/nixos/modules/services/misc/sourcehut/default.nix b/nixos/modules/services/misc/sourcehut/default.nix
index 7dd254e3492..da3bf069813 100644
--- a/nixos/modules/services/misc/sourcehut/default.nix
+++ b/nixos/modules/services/misc/sourcehut/default.nix
@@ -1390,6 +1390,8 @@ in
     '')
   ];
 
+  # Don't edit the docbook xml directly, edit the md and generate it:
+  # `pandoc sourcehut.md -t docbook --top-level-division=chapter --extract-media=media -f markdown-smart --lua-filter ../../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > sourcehut.xml`
   meta.doc = ./sourcehut.xml;
   meta.maintainers = with maintainers; [ tomberek ];
 }
diff --git a/nixos/modules/services/misc/sourcehut/sourcehut.md b/nixos/modules/services/misc/sourcehut/sourcehut.md
new file mode 100644
index 00000000000..44d58aa0bef
--- /dev/null
+++ b/nixos/modules/services/misc/sourcehut/sourcehut.md
@@ -0,0 +1,93 @@
+# Sourcehut {#module-services-sourcehut}
+
+[Sourcehut](https://sr.ht.com/) is an open-source,
+self-hostable software development platform. The server setup can be automated using
+[services.sourcehut](#opt-services.sourcehut.enable).
+
+## Basic usage {#module-services-sourcehut-basic-usage}
+
+Sourcehut is a Python and Go based set of applications.
+This NixOS module also provides basic configuration integrating Sourcehut into locally running
+`services.nginx`, `services.redis.servers.sourcehut`, `services.postfix`
+and `services.postgresql` services.
+
+A very basic configuration may look like this:
+```
+{ pkgs, ... }:
+let
+  fqdn =
+    let
+      join = hostName: domain: hostName + optionalString (domain != null) ".${domain}";
+    in join config.networking.hostName config.networking.domain;
+in {
+
+  networking = {
+    hostName = "srht";
+    domain = "tld";
+    firewall.allowedTCPPorts = [ 22 80 443 ];
+  };
+
+  services.sourcehut = {
+    enable = true;
+    git.enable = true;
+    man.enable = true;
+    meta.enable = true;
+    nginx.enable = true;
+    postfix.enable = true;
+    postgresql.enable = true;
+    redis.enable = true;
+    settings = {
+        "sr.ht" = {
+          environment = "production";
+          global-domain = fqdn;
+          origin = "https://${fqdn}";
+          # Produce keys with srht-keygen from sourcehut.coresrht.
+          network-key = "/run/keys/path/to/network-key";
+          service-key = "/run/keys/path/to/service-key";
+        };
+        webhooks.private-key= "/run/keys/path/to/webhook-key";
+    };
+  };
+
+  security.acme.certs."${fqdn}".extraDomainNames = [
+    "meta.${fqdn}"
+    "man.${fqdn}"
+    "git.${fqdn}"
+  ];
+
+  services.nginx = {
+    enable = true;
+    # only recommendedProxySettings are strictly required, but the rest make sense as well.
+    recommendedTlsSettings = true;
+    recommendedOptimisation = true;
+    recommendedGzipSettings = true;
+    recommendedProxySettings = true;
+
+    # Settings to setup what certificates are used for which endpoint.
+    virtualHosts = {
+      "${fqdn}".enableACME = true;
+      "meta.${fqdn}".useACMEHost = fqdn:
+      "man.${fqdn}".useACMEHost = fqdn:
+      "git.${fqdn}".useACMEHost = fqdn:
+    };
+  };
+}
+```
+
+  The `hostName` option is used internally to configure the nginx
+reverse-proxy. The `settings` attribute set is
+used by the configuration generator and the result is placed in `/etc/sr.ht/config.ini`.
+
+## Configuration {#module-services-sourcehut-configuration}
+
+All configuration parameters are also stored in
+`/etc/sr.ht/config.ini` which is generated by
+the module and linked from the store to ensure that all values from `config.ini`
+can be modified by the module.
+
+## Using an alternative webserver as reverse-proxy (e.g. `httpd`) {#module-services-sourcehut-httpd}
+
+By default, `nginx` is used as reverse-proxy for `sourcehut`.
+However, it's possible to use e.g. `httpd` by explicitly disabling
+`nginx` using [](#opt-services.nginx.enable) and fixing the
+`settings`.
diff --git a/nixos/modules/services/misc/sourcehut/sourcehut.xml b/nixos/modules/services/misc/sourcehut/sourcehut.xml
index 5f9cc75bc9f..883b6f01ef8 100644
--- a/nixos/modules/services/misc/sourcehut/sourcehut.xml
+++ b/nixos/modules/services/misc/sourcehut/sourcehut.xml
@@ -1,41 +1,36 @@
-<chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         version="5.0"
-         xml:id="module-services-sourcehut">
- <title>Sourcehut</title>
- <para>
-  <link xlink:href="https://sr.ht.com/">Sourcehut</link> is an open-source,
-  self-hostable software development platform. The server setup can be automated using
-  <link linkend="opt-services.sourcehut.enable">services.sourcehut</link>.
- </para>
-
- <section xml:id="module-services-sourcehut-basic-usage">
-  <title>Basic usage</title>
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-sourcehut">
+  <title>Sourcehut</title>
   <para>
-   Sourcehut is a Python and Go based set of applications.
-   This NixOS module also provides basic configuration integrating Sourcehut into locally running
-   <literal>services.nginx</literal>,
-   <literal>services.redis.servers.sourcehut</literal>,
-   <literal>services.postfix</literal>
-   and
-   <literal>services.postgresql</literal> services.
+    <link xlink:href="https://sr.ht.com/">Sourcehut</link> is an
+    open-source, self-hostable software development platform. The server
+    setup can be automated using
+    <link linkend="opt-services.sourcehut.enable">services.sourcehut</link>.
   </para>
-
-  <para>
-   A very basic configuration may look like this:
-<programlisting>
+  <section xml:id="module-services-sourcehut-basic-usage">
+    <title>Basic usage</title>
+    <para>
+      Sourcehut is a Python and Go based set of applications. This NixOS
+      module also provides basic configuration integrating Sourcehut
+      into locally running <literal>services.nginx</literal>,
+      <literal>services.redis.servers.sourcehut</literal>,
+      <literal>services.postfix</literal> and
+      <literal>services.postgresql</literal> services.
+    </para>
+    <para>
+      A very basic configuration may look like this:
+    </para>
+    <programlisting>
 { pkgs, ... }:
 let
   fqdn =
     let
-      join = hostName: domain: hostName + optionalString (domain != null) ".${domain}";
+      join = hostName: domain: hostName + optionalString (domain != null) &quot;.${domain}&quot;;
     in join config.networking.hostName config.networking.domain;
 in {
 
   networking = {
-    hostName = "srht";
-    domain = "tld";
+    hostName = &quot;srht&quot;;
+    domain = &quot;tld&quot;;
     firewall.allowedTCPPorts = [ 22 80 443 ];
   };
 
@@ -49,22 +44,22 @@ in {
     postgresql.enable = true;
     redis.enable = true;
     settings = {
-        "sr.ht" = {
-          environment = "production";
+        &quot;sr.ht&quot; = {
+          environment = &quot;production&quot;;
           global-domain = fqdn;
-          origin = "https://${fqdn}";
+          origin = &quot;https://${fqdn}&quot;;
           # Produce keys with srht-keygen from sourcehut.coresrht.
-          network-key = "/run/keys/path/to/network-key";
-          service-key = "/run/keys/path/to/service-key";
+          network-key = &quot;/run/keys/path/to/network-key&quot;;
+          service-key = &quot;/run/keys/path/to/service-key&quot;;
         };
-        webhooks.private-key= "/run/keys/path/to/webhook-key";
+        webhooks.private-key= &quot;/run/keys/path/to/webhook-key&quot;;
     };
   };
 
-  security.acme.certs."${fqdn}".extraDomainNames = [
-    "meta.${fqdn}"
-    "man.${fqdn}"
-    "git.${fqdn}"
+  security.acme.certs.&quot;${fqdn}&quot;.extraDomainNames = [
+    &quot;meta.${fqdn}&quot;
+    &quot;man.${fqdn}&quot;
+    &quot;git.${fqdn}&quot;
   ];
 
   services.nginx = {
@@ -77,43 +72,40 @@ in {
 
     # Settings to setup what certificates are used for which endpoint.
     virtualHosts = {
-      "${fqdn}".enableACME = true;
-      "meta.${fqdn}".useACMEHost = fqdn:
-      "man.${fqdn}".useACMEHost = fqdn:
-      "git.${fqdn}".useACMEHost = fqdn:
+      &quot;${fqdn}&quot;.enableACME = true;
+      &quot;meta.${fqdn}&quot;.useACMEHost = fqdn:
+      &quot;man.${fqdn}&quot;.useACMEHost = fqdn:
+      &quot;git.${fqdn}&quot;.useACMEHost = fqdn:
     };
   };
 }
 </programlisting>
-  </para>
-
-  <para>
-   The <literal>hostName</literal> option is used internally to configure the nginx
-   reverse-proxy. The <literal>settings</literal> attribute set is
-   used by the configuration generator and the result is placed in <literal>/etc/sr.ht/config.ini</literal>.
-  </para>
- </section>
-
- <section xml:id="module-services-sourcehut-configuration">
-  <title>Configuration</title>
-
-  <para>
-   All configuration parameters are also stored in
-   <literal>/etc/sr.ht/config.ini</literal> which is generated by
-   the module and linked from the store to ensure that all values from <literal>config.ini</literal>
-   can be modified by the module.
-  </para>
-
- </section>
-
- <section xml:id="module-services-sourcehut-httpd">
-  <title>Using an alternative webserver as reverse-proxy (e.g. <literal>httpd</literal>)</title>
-  <para>
-   By default, <literal>nginx</literal> is used as reverse-proxy for <literal>sourcehut</literal>.
-   However, it's possible to use e.g. <literal>httpd</literal> by explicitly disabling
-   <literal>nginx</literal> using <xref linkend="opt-services.nginx.enable" /> and fixing the
-   <literal>settings</literal>.
-  </para>
-</section>
-
+    <para>
+      The <literal>hostName</literal> option is used internally to
+      configure the nginx reverse-proxy. The <literal>settings</literal>
+      attribute set is used by the configuration generator and the
+      result is placed in <literal>/etc/sr.ht/config.ini</literal>.
+    </para>
+  </section>
+  <section xml:id="module-services-sourcehut-configuration">
+    <title>Configuration</title>
+    <para>
+      All configuration parameters are also stored in
+      <literal>/etc/sr.ht/config.ini</literal> which is generated by the
+      module and linked from the store to ensure that all values from
+      <literal>config.ini</literal> can be modified by the module.
+    </para>
+  </section>
+  <section xml:id="module-services-sourcehut-httpd">
+    <title>Using an alternative webserver as reverse-proxy (e.g.
+    <literal>httpd</literal>)</title>
+    <para>
+      By default, <literal>nginx</literal> is used as reverse-proxy for
+      <literal>sourcehut</literal>. However, it's possible to use e.g.
+      <literal>httpd</literal> by explicitly disabling
+      <literal>nginx</literal> using
+      <xref linkend="opt-services.nginx.enable"></xref> and fixing the
+      <literal>settings</literal>.
+    </para>
+  </section>
 </chapter>