Merge pull request #208762 from ncfavier/link-manpages-options-doc

doc/Makefile

@@ -11,7 +11,7 @@ pandoc_commonmark_enabled_extensions = +attributes+fenced_divs+footnotes+bracket
 pandoc_flags = --extract-media=$(pandoc_media_dir) \
 	--lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \
 	--lua-filter=build-aux/pandoc-filters/myst-reader/roles.lua \
-	--lua-filter=build-aux/pandoc-filters/link-unix-man-references.lua \
+	--lua-filter=$(PANDOC_LINK_MANPAGES_FILTER) \
 	--lua-filter=build-aux/pandoc-filters/docbook-writer/rst-roles.lua \
 	--lua-filter=build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua \
 	-f commonmark$(pandoc_commonmark_enabled_extensions)+smart

doc/build-aux/pandoc-filters/link-manpages.nix

@@ -0,0 +1,28 @@
+{ pkgs ? import ../../.. {} }:
+let
+  inherit (pkgs) lib;
+  manpageURLs = builtins.fromJSON (builtins.readFile (pkgs.path + "/doc/manpage-urls.json"));
+in pkgs.writeText "link-manpages.lua" ''
+  --[[
+  Adds links to known man pages that aren't already in a link.
+  ]]
+
+  local manpage_urls = {
+  ${lib.concatStringsSep "\n" (lib.mapAttrsToList (man: url:
+    "  [${builtins.toJSON man}] = ${builtins.toJSON url},") manpageURLs)}
+  }
+
+  traverse = 'topdown'
+
+  -- Returning false as the second value aborts processing of child elements.
+  function Link(elem)
+    return elem, false
+  end
+
+  function Code(elem)
+    local is_man_role = elem.classes:includes('interpreted-text') and elem.attributes['role'] == 'manpage'
+    if is_man_role and manpage_urls[elem.text] ~= nil then
+      return pandoc.Link(elem, manpage_urls[elem.text]), false
+    end
+  end
+''

doc/build-aux/pandoc-filters/link-unix-man-references.lua

@@ -1,38 +0,0 @@
---[[
-Turns a manpage reference into a link, when a mapping is defined below.
-]]
-
-local man_urls = {
-  ["nix.conf(5)"] = "https://nixos.org/manual/nix/stable/#sec-conf-file",
-
-  ["journald.conf(5)"] = "https://www.freedesktop.org/software/systemd/man/journald.conf.html",
-  ["logind.conf(5)"] = "https://www.freedesktop.org/software/systemd/man/logind.conf.html",
-  ["networkd.conf(5)"] = "https://www.freedesktop.org/software/systemd/man/networkd.conf.html",
-  ["systemd.automount(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.automount.html",
-  ["systemd.exec(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.exec.html",
-  ["systemd.link(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.link.html",
-  ["systemd.mount(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.mount.html",
-  ["systemd.netdev(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.netdev.html",
-  ["systemd.network(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.network.html",
-  ["systemd.nspawn(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.nspawn.html",
-  ["systemd.path(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.path.html",
-  ["systemd.resource-control(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.resource-control.html",
-  ["systemd.scope(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.scope.html",
-  ["systemd.service(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.service.html",
-  ["systemd.slice(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.slice.html",
-  ["systemd.socket(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.socket.html",
-  ["systemd.timer(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.timer.html",
-  ["systemd.unit(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.unit.html",
-  ["timesyncd.conf(5)"] = "https://www.freedesktop.org/software/systemd/man/timesyncd.conf.html",
-  ["tmpfiles.d(5)"] = "https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html",
-  ["systemd.time(7)"] = "https://www.freedesktop.org/software/systemd/man/systemd.time.html",
-  ["systemd-fstab-generator(8)"] = "https://www.freedesktop.org/software/systemd/man/systemd-fstab-generator.html",
-  ["systemd-networkd-wait-online.service(8)"] = "https://www.freedesktop.org/software/systemd/man/systemd-networkd-wait-online.service.html",
-}
-
-function Code(elem)
-  local is_man_role = elem.classes:includes('interpreted-text') and elem.attributes['role'] == 'manpage'
-  if is_man_role and man_urls[elem.text] ~= nil then
-    return pandoc.Link(elem, man_urls[elem.text])
-  end
-end

doc/contributing/contributing-to-documentation.chapter.md

@@ -53,7 +53,7 @@ Additional syntax extensions are available, though not all extensions can be use
   This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing).
 
 - []{#ssec-contributing-markup-inline-roles}
-  If you want to link to a man page, you can use `` {manpage}`nix.conf(5)` ``, which will turn into {manpage}`nix.conf(5)`. The references will turn into links when a mapping exists in {file}`doc/build-aux/pandoc-filters/link-unix-man-references.lua`.
+  If you want to link to a man page, you can use `` {manpage}`nix.conf(5)` ``, which will turn into {manpage}`nix.conf(5)`. The references will turn into links when a mapping exists in {file}`doc/manpage-urls.json`.
 
   A few markups for other kinds of literals are also available:
 

doc/default.nix

@@ -36,4 +36,5 @@ in pkgs.stdenv.mkDerivation {
 
   # Environment variables
   PANDOC_LUA_FILTERS_DIR = "${pkgs.pandoc-lua-filters}/share/pandoc/filters";
+  PANDOC_LINK_MANPAGES_FILTER = import build-aux/pandoc-filters/link-manpages.nix { inherit pkgs; };
 }

doc/manpage-urls.json

@@ -0,0 +1,29 @@
+{
+  "nix.conf(5)": "https://nixos.org/manual/nix/stable/#sec-conf-file",
+
+  "journald.conf(5)": "https://www.freedesktop.org/software/systemd/man/journald.conf.html",
+  "logind.conf(5)": "https://www.freedesktop.org/software/systemd/man/logind.conf.html",
+  "networkd.conf(5)": "https://www.freedesktop.org/software/systemd/man/networkd.conf.html",
+  "systemd.automount(5)": "https://www.freedesktop.org/software/systemd/man/systemd.automount.html",
+  "systemd.exec(5)": "https://www.freedesktop.org/software/systemd/man/systemd.exec.html",
+  "systemd.link(5)": "https://www.freedesktop.org/software/systemd/man/systemd.link.html",
+  "systemd.mount(5)": "https://www.freedesktop.org/software/systemd/man/systemd.mount.html",
+  "systemd.netdev(5)": "https://www.freedesktop.org/software/systemd/man/systemd.netdev.html",
+  "systemd.network(5)": "https://www.freedesktop.org/software/systemd/man/systemd.network.html",
+  "systemd.nspawn(5)": "https://www.freedesktop.org/software/systemd/man/systemd.nspawn.html",
+  "systemd.path(5)": "https://www.freedesktop.org/software/systemd/man/systemd.path.html",
+  "systemd.resource-control(5)": "https://www.freedesktop.org/software/systemd/man/systemd.resource-control.html",
+  "systemd.scope(5)": "https://www.freedesktop.org/software/systemd/man/systemd.scope.html",
+  "systemd.service(5)": "https://www.freedesktop.org/software/systemd/man/systemd.service.html",
+  "systemd.slice(5)": "https://www.freedesktop.org/software/systemd/man/systemd.slice.html",
+  "systemd.socket(5)": "https://www.freedesktop.org/software/systemd/man/systemd.socket.html",
+  "systemd.timer(5)": "https://www.freedesktop.org/software/systemd/man/systemd.timer.html",
+  "systemd.unit(5)": "https://www.freedesktop.org/software/systemd/man/systemd.unit.html",
+  "systemd-system.conf(5)": "https://www.freedesktop.org/software/systemd/man/systemd-system.conf.html",
+  "systemd-user.conf(5)": "https://www.freedesktop.org/software/systemd/man/systemd-user.conf.html",
+  "timesyncd.conf(5)": "https://www.freedesktop.org/software/systemd/man/timesyncd.conf.html",
+  "tmpfiles.d(5)": "https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html",
+  "systemd.time(7)": "https://www.freedesktop.org/software/systemd/man/systemd.time.html",
+  "systemd-fstab-generator(8)": "https://www.freedesktop.org/software/systemd/man/systemd-fstab-generator.html",
+  "systemd-networkd-wait-online.service(8)": "https://www.freedesktop.org/software/systemd/man/systemd-networkd-wait-online.service.html"
+}

maintainers/scripts/db-to-md.sh

@@ -41,7 +41,7 @@ pandoc_flags=(
     # - diagram-generator.lua (we do not support that in NixOS manual to limit dependencies)
     # - media extraction (was only required for diagram generator)
     # - myst-reader/roles.lua (only relevant for MyST → DocBook)
-    # - link-unix-man-references.lua (links should only be added to display output)
+    # - link-manpages.lua (links should only be added to display output)
     # - docbook-writer/rst-roles.lua (only relevant for → DocBook)
     # - docbook-writer/labelless-link-is-xref.lua (only relevant for → DocBook)
     "--lua-filter=$DIR/../../doc/build-aux/pandoc-filters/docbook-reader/citerefentry-to-rst-role.lua"

nixos/doc/manual/md-to-db.sh

@@ -8,6 +8,8 @@
 DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
 pushd "$DIR"
 
+link_manpages_filter=$(nix-build --no-out-link "$DIR/../../../doc/build-aux/pandoc-filters/link-manpages.nix")
+
 # NOTE: Keep in sync with Nixpkgs manual (/doc/Makefile).
 # TODO: Remove raw-attribute when we can get rid of DocBook altogether.
 pandoc_commonmark_enabled_extensions=+attributes+fenced_divs+footnotes+bracketed_spans+definition_lists+pipe_tables+raw_attribute
@@ -17,7 +19,7 @@ pandoc_flags=(
   # - media extraction (was only required for diagram generator)
   # - docbook-reader/citerefentry-to-rst-role.lua (only relevant for DocBook → MarkDown/rST/MyST)
   "--lua-filter=$DIR/../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua"
-  "--lua-filter=$DIR/../../../doc/build-aux/pandoc-filters/link-unix-man-references.lua"
+  "--lua-filter=$link_manpages_filter"
   "--lua-filter=$DIR/../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua"
   "--lua-filter=$DIR/../../../doc/build-aux/pandoc-filters/docbook-writer/html-elements.lua"
   "--lua-filter=$DIR/../../../doc/build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua"

nixos/lib/make-options-doc/default.nix

@@ -131,6 +131,8 @@ in rec {
         if baseOptionsJSON == null
         then builtins.toFile "base.json" "{}"
         else baseOptionsJSON;
+
+      MANPAGE_URLS = pkgs.path + "/doc/manpage-urls.json";
     }
     ''
       # Export list of options in different format.

nixos/lib/make-options-doc/mergeJSON.py

@@ -1,5 +1,6 @@
 import collections
 import json
+import os
 import sys
 from typing import Any, Dict, List
 
@@ -46,6 +47,8 @@ def unpivot(options: Dict[Key, Option]) -> Dict[str, JSON]:
         result[opt.name] = opt.value
     return result
 
+manpage_urls = json.load(open(os.getenv('MANPAGE_URLS')))
+
 admonitions = {
     '.warning': 'warning',
     '.important': 'important',
@@ -119,9 +122,14 @@ class Renderer(mistune.renderers.BaseRenderer):
     def env(self, text):
         return f"<envar>{escape(text)}</envar>"
     def manpage(self, page, section):
+        man = f"{page}({section})"
         title = f"<refentrytitle>{escape(page)}</refentrytitle>"
         vol = f"<manvolnum>{escape(section)}</manvolnum>"
-        return f"<citerefentry>{title}{vol}</citerefentry>"
+        ref = f"<citerefentry>{title}{vol}</citerefentry>"
+        if man in manpage_urls:
+            return self.link(manpage_urls[man], text=ref)
+        else:
+            return ref
 
     def finalize(self, data):
         return "".join(data)

nixos/lib/systemd-unit-options.nix

@@ -60,7 +60,7 @@ in rec {
         `asDropin` creates a drop-in file named `overrides.conf`.
         Mainly needed to define instances for systemd template units (e.g. `systemd-nspawn@mycontainer.service`).
 
-        See also systemd.unit(1).
+        See also {manpage}`systemd.unit(5)`.
       '';
     };
 
@@ -86,7 +86,7 @@ in rec {
 
         This option creates a `.wants` symlink in the given target that exists
         statelessly without the need for running `systemctl enable`.
-        The in systemd.unit(5) manpage described `[Install]` section however is
+        The `[Install]` section described in {manpage}`systemd.unit(5)` however is
         not supported because it is a stateful process that does not fit well
         into the NixOS design.
       '';

nixos/modules/services/backup/restic.nix

@@ -132,7 +132,7 @@ in
             OnCalendar = "daily";
           };
           description = lib.mdDoc ''
-            When to run the backup. See man systemd.timer for details.
+            When to run the backup. See {manpage}`systemd.timer(5)` for details.
           '';
           example = {
             OnCalendar = "00:05";

nixos/modules/services/networking/kresd.nix

@@ -79,7 +79,7 @@ in {
       example = [ "53" ];
       description = lib.mdDoc ''
         What addresses and ports the server should listen on.
-        For detailed syntax see ListenStream in man systemd.socket.
+        For detailed syntax see ListenStream in {manpage}`systemd.socket(5)`.
       '';
     };
     listenTLS = mkOption {
@@ -88,7 +88,7 @@ in {
       example = [ "198.51.100.1:853" "[2001:db8::1]:853" "853" ];
       description = lib.mdDoc ''
         Addresses and ports on which kresd should provide DNS over TLS (see RFC 7858).
-        For detailed syntax see ListenStream in man systemd.socket.
+        For detailed syntax see ListenStream in {manpage}`systemd.socket(5)`.
       '';
     };
     listenDoH = mkOption {
@@ -97,7 +97,7 @@ in {
       example = [ "198.51.100.1:443" "[2001:db8::1]:443" "443" ];
       description = lib.mdDoc ''
         Addresses and ports on which kresd should provide DNS over HTTPS/2 (see RFC 8484).
-        For detailed syntax see ListenStream in man systemd.socket.
+        For detailed syntax see ListenStream in {manpage}`systemd.socket(5)`.
       '';
     };
     instances = mkOption {

nixos/modules/system/boot/systemd/user.nix

@@ -46,7 +46,7 @@ in {
       type = types.lines;
       example = "DefaultCPUAccounting=yes";
       description = lib.mdDoc ''
-        Extra config options for systemd user instances. See man systemd-user.conf for
+        Extra config options for systemd user instances. See {manpage}`systemd-user.conf(5)` for
         available options.
       '';
     };