nixos/manual: render module chapters with nixos-render-docs

this converts meta.doc into an md pointer, not an xml pointer. since we
no longer need xml for manual chapters we can also remove support for
manual chapters from md-to-db.sh

since pandoc converts smart quotes to docbook quote elements and our
nixos-render-docs does not we lose this distinction in the rendered
output. that's probably not that bad, our stylesheet didn't make use of
this anyway (and pre-23.05 versions of the chapters didn't use quote
elements either).

also updates the nixpkgs manual to clarify that option docs support all
extensions (although it doesn't support headings at all, so heading
anchors don't work by extension).

2 files changed, 1 insertions, 62 deletions

diff --git a/nixos/modules/services/development/blackfire.nix b/nixos/modules/services/development/blackfire.nix
index 054cef9ae80b..3c98d7a281c6 100644
--- a/nixos/modules/services/development/blackfire.nix
+++ b/nixos/modules/services/development/blackfire.nix
@@ -11,7 +11,7 @@ let
 in {
   meta = {
     maintainers = pkgs.blackfire.meta.maintainers;
-    doc = ./blackfire.xml;
+    doc = ./blackfire.md;
   };
 
   options = {
diff --git a/nixos/modules/services/development/blackfire.xml b/nixos/modules/services/development/blackfire.xml
deleted file mode 100644
index 842e5bec97d5..000000000000
--- a/nixos/modules/services/development/blackfire.xml
+++ /dev/null
@@ -1,61 +0,0 @@
-<!-- Do not edit this file directly, edit its companion .md instead
-     and regenerate this file using nixos/doc/manual/md-to-db.sh -->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-blackfire">
-  <title>Blackfire profiler</title>
-  <para>
-    <emphasis>Source:</emphasis>
-    <filename>modules/services/development/blackfire.nix</filename>
-  </para>
-  <para>
-    <emphasis>Upstream documentation:</emphasis>
-    <link xlink:href="https://blackfire.io/docs/introduction">https://blackfire.io/docs/introduction</link>
-  </para>
-  <para>
-    <link xlink:href="https://blackfire.io">Blackfire</link> is a
-    proprietary tool for profiling applications. There are several
-    languages supported by the product but currently only PHP support is
-    packaged in Nixpkgs. The back-end consists of a module that is
-    loaded into the language runtime (called <emphasis>probe</emphasis>)
-    and a service (<emphasis>agent</emphasis>) that the probe connects
-    to and that sends the profiles to the server.
-  </para>
-  <para>
-    To use it, you will need to enable the agent and the probe on your
-    server. The exact method will depend on the way you use PHP but here
-    is an example of NixOS configuration for PHP-FPM:
-  </para>
-  <programlisting>
-let
-  php = pkgs.php.withExtensions ({ enabled, all }: enabled ++ (with all; [
-    blackfire
-  ]));
-in {
-  # Enable the probe extension for PHP-FPM.
-  services.phpfpm = {
-    phpPackage = php;
-  };
-
-  # Enable and configure the agent.
-  services.blackfire-agent = {
-    enable = true;
-    settings = {
-      # You will need to get credentials at https://blackfire.io/my/settings/credentials
-      # You can also use other options described in https://blackfire.io/docs/up-and-running/configuration/agent
-      server-id = &quot;XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&quot;;
-      server-token = &quot;XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&quot;;
-    };
-  };
-
-  # Make the agent run on start-up.
-  # (WantedBy= from the upstream unit not respected: https://github.com/NixOS/nixpkgs/issues/81138)
-  # Alternately, you can start it manually with `systemctl start blackfire-agent`.
-  systemd.services.blackfire-agent.wantedBy = [ &quot;phpfpm-foo.service&quot; ];
-}
-</programlisting>
-  <para>
-    On your developer machine, you will also want to install
-    <link xlink:href="https://blackfire.io/docs/up-and-running/installation#install-a-profiling-client">the
-    client</link> (see <literal>blackfire</literal> package) or the
-    browser extension to actually trigger the profiling.
-  </para>
-</chapter>