commit 1229e735ac51dbe79724f7648655a2089c9c67b9 · pyrox.dev/nixpkgs

+4 -4

nixos/doc/manual/administration/containers.chapter.md

···

       21
        
       approach, containers are configured and updated independently from the

     

       22
        
       host system.

     

       23
        
       

     

       24
       -
       ```{=docbook}

     

       25
       -
       <xi:include href="imperative-containers.section.xml" />

     

       26
       -
       <xi:include href="declarative-containers.section.xml" />

     

       27
       -
       <xi:include href="container-networking.section.xml" />

     

       28
        
       ```

···

       21
        
       approach, containers are configured and updated independently from the

     

       22
        
       host system.

     

       23
        
       

     

       24
       +
       ```{=include=} sections

     

       25
       +
       imperative-containers.section.md

     

       26
       +
       declarative-containers.section.md

     

       27
       +
       container-networking.section.md

     

       28
        
       ```

+14

nixos/doc/manual/administration/running.md

···

       1
       +
       # Administration {#ch-running}

     

       2
       +
       

     

       3
       +
       This chapter describes various aspects of managing a running NixOS system, such as how to use the {command}`systemd` service manager.

     

       4
       +
       

     

       5
       +
       ```{=include=} chapters

     

       6
       +
       service-mgmt.chapter.md

     

       7
       +
       rebooting.chapter.md

     

       8
       +
       user-sessions.chapter.md

     

       9
       +
       control-groups.chapter.md

     

       10
       +
       logging.chapter.md

     

       11
       +
       cleaning-store.chapter.md

     

       12
       +
       containers.chapter.md

     

       13
       +
       troubleshooting.chapter.md

     

       14
       +
       ```

-21

nixos/doc/manual/administration/running.xml

···

       1
       -
       <part xmlns="http://docbook.org/ns/docbook"

     

       2
       -
             xmlns:xlink="http://www.w3.org/1999/xlink"

     

       3
       -
             xmlns:xi="http://www.w3.org/2001/XInclude"

     

       4
       -
             version="5.0"

     

       5
       -
             xml:id="ch-running">

     

       6
       -
        <title>Administration</title>

     

       7
       -
        <partintro xml:id="ch-running-intro">

     

       8
       -
         <para>

     

       9
       -
          This chapter describes various aspects of managing a running NixOS system,

     

       10
       -
          such as how to use the <command>systemd</command> service manager.

     

       11
       -
         </para>

     

       12
       -
        </partintro>

     

       13
       -
        <xi:include href="../from_md/administration/service-mgmt.chapter.xml" />

     

       14
       -
        <xi:include href="../from_md/administration/rebooting.chapter.xml" />

     

       15
       -
        <xi:include href="../from_md/administration/user-sessions.chapter.xml" />

     

       16
       -
        <xi:include href="../from_md/administration/control-groups.chapter.xml" />

     

       17
       -
        <xi:include href="../from_md/administration/logging.chapter.xml" />

     

       18
       -
        <xi:include href="../from_md/administration/cleaning-store.chapter.xml" />

     

       19
       -
        <xi:include href="../from_md/administration/containers.chapter.xml" />

     

       20
       -
        <xi:include href="../from_md/administration/troubleshooting.chapter.xml" />

     

       21
       -
       </part>

+6 -6

nixos/doc/manual/administration/troubleshooting.chapter.md

···

       3
        
       This chapter describes solutions to common problems you might encounter

     

       4
        
       when you manage your NixOS system.

     

       5
        
       

     

       6
       -
       ```{=docbook}

     

       7
       -
       <xi:include href="boot-problems.section.xml" />

     

       8
       -
       <xi:include href="maintenance-mode.section.xml" />

     

       9
       -
       <xi:include href="rollback.section.xml" />

     

       10
       -
       <xi:include href="store-corruption.section.xml" />

     

       11
       -
       <xi:include href="network-problems.section.xml" />

     

       12
        
       ```

···

       3
        
       This chapter describes solutions to common problems you might encounter

     

       4
        
       when you manage your NixOS system.

     

       5
        
       

     

       6
       +
       ```{=include=} sections

     

       7
       +
       boot-problems.section.md

     

       8
       +
       maintenance-mode.section.md

     

       9
       +
       rollback.section.md

     

       10
       +
       store-corruption.section.md

     

       11
       +
       network-problems.section.md

     

       12
        
       ```

+4 -4

nixos/doc/manual/configuration/config-syntax.chapter.md

···

       11
        
       here we give a short overview of the most important constructs useful in

     

       12
        
       NixOS configuration files.

     

       13
        
       

     

       14
       -
       ```{=docbook}

     

       15
       -
       <xi:include href="config-file.section.xml" />

     

       16
       -
       <xi:include href="abstractions.section.xml" />

     

       17
       -
       <xi:include href="modularity.section.xml" />

     

       18
        
       ```

···

       11
        
       here we give a short overview of the most important constructs useful in

     

       12
        
       NixOS configuration files.

     

       13
        
       

     

       14
       +
       ```{=include=} sections

     

       15
       +
       config-file.section.md

     

       16
       +
       abstractions.section.md

     

       17
       +
       modularity.section.md

     

       18
        
       ```

+27

nixos/doc/manual/configuration/configuration.md

···

       1
       +
       # Configuration {#ch-configuration}

     

       2
       +
       

     

       3
       +
       This chapter describes how to configure various aspects of a NixOS machine through the configuration file {file}`/etc/nixos/configuration.nix`. As described in [](#sec-changing-config), changes to this file only take effect after you run {command}`nixos-rebuild`.

     

       4
       +
       

     

       5
       +
       ```{=include=} chapters

     

       6
       +
       config-syntax.chapter.md

     

       7
       +
       package-mgmt.chapter.md

     

       8
       +
       user-mgmt.chapter.md

     

       9
       +
       file-systems.chapter.md

     

       10
       +
       x-windows.chapter.md

     

       11
       +
       wayland.chapter.md

     

       12
       +
       gpu-accel.chapter.md

     

       13
       +
       xfce.chapter.md

     

       14
       +
       networking.chapter.md

     

       15
       +
       linux-kernel.chapter.md

     

       16
       +
       subversion.chapter.md

     

       17
       +
       ```

     

       18
       +
       

     

       19
       +
       ```{=include=} chapters

     

       20
       +
       @MODULE_CHAPTERS@

     

       21
       +
       ```

     

       22
       +
       

     

       23
       +
       ```{=include=} chapters

     

       24
       +
       profiles.chapter.md

     

       25
       +
       kubernetes.chapter.md

     

       26
       +
       ```

     

       27
       +
       <!-- Apache; libvirtd virtualisation -->

-31

nixos/doc/manual/configuration/configuration.xml

···

       1
       -
       <part xmlns="http://docbook.org/ns/docbook"

     

       2
       -
             xmlns:xlink="http://www.w3.org/1999/xlink"

     

       3
       -
             xmlns:xi="http://www.w3.org/2001/XInclude"

     

       4
       -
             version="5.0"

     

       5
       -
             xml:id="ch-configuration">

     

       6
       -
        <title>Configuration</title>

     

       7
       -
        <partintro xml:id="ch-configuration-intro">

     

       8
       -
         <para>

     

       9
       -
          This chapter describes how to configure various aspects of a NixOS machine

     

       10
       -
          through the configuration file

     

       11
       -
          <filename>/etc/nixos/configuration.nix</filename>. As described in

     

       12
       -
          <xref linkend="sec-changing-config" />, changes to this file only take

     

       13
       -
          effect after you run <command>nixos-rebuild</command>.

     

       14
       -
         </para>

     

       15
       -
        </partintro>

     

       16
       -
        <xi:include href="../from_md/configuration/config-syntax.chapter.xml" />

     

       17
       -
        <xi:include href="../from_md/configuration/package-mgmt.chapter.xml" />

     

       18
       -
        <xi:include href="../from_md/configuration/user-mgmt.chapter.xml" />

     

       19
       -
        <xi:include href="../from_md/configuration/file-systems.chapter.xml" />

     

       20
       -
        <xi:include href="../from_md/configuration/x-windows.chapter.xml" />

     

       21
       -
        <xi:include href="../from_md/configuration/wayland.chapter.xml" />

     

       22
       -
        <xi:include href="../from_md/configuration/gpu-accel.chapter.xml" />

     

       23
       -
        <xi:include href="../from_md/configuration/xfce.chapter.xml" />

     

       24
       -
        <xi:include href="../from_md/configuration/networking.chapter.xml" />

     

       25
       -
        <xi:include href="../from_md/configuration/linux-kernel.chapter.xml" />

     

       26
       -
        <xi:include href="../from_md/configuration/subversion.chapter.xml" />

     

       27
       -
        <xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" />

     

       28
       -
        <xi:include href="../from_md/configuration/profiles.chapter.xml" />

     

       29
       -
        <xi:include href="../from_md/configuration/kubernetes.chapter.xml" />

     

       30
       -
       <!-- Apache; libvirtd virtualisation -->

     

       31
       -
       </part>

+3 -3

nixos/doc/manual/configuration/declarative-packages.section.md

···

       40
        
       To "uninstall" a package, simply remove it from

     

       41
        
       [](#opt-environment.systemPackages) and run `nixos-rebuild switch`.

     

       42
        
       

     

       43
       -
       ```{=docbook}

     

       44
       -
       <xi:include href="customizing-packages.section.xml" />

     

       45
       -
       <xi:include href="adding-custom-packages.section.xml" />

     

       46
        
       ```

···

       40
        
       To "uninstall" a package, simply remove it from

     

       41
        
       [](#opt-environment.systemPackages) and run `nixos-rebuild switch`.

     

       42
        
       

     

       43
       +
       ```{=include=} sections

     

       44
       +
       customizing-packages.section.md

     

       45
       +
       adding-custom-packages.section.md

     

       46
        
       ```

+3 -3

nixos/doc/manual/configuration/file-systems.chapter.md

···

       36
        
       and non-critical by adding `options = [ "nofail" ];`.

     

       37
        
       :::

     

       38
        
       

     

       39
       -
       ```{=docbook}

     

       40
       -
       <xi:include href="luks-file-systems.section.xml" />

     

       41
       -
       <xi:include href="sshfs-file-systems.section.xml" />

     

       42
        
       ```

···

       36
        
       and non-critical by adding `options = [ "nofail" ];`.

     

       37
        
       :::

     

       38
        
       

     

       39
       +
       ```{=include=} sections

     

       40
       +
       luks-file-systems.section.md

     

       41
       +
       sshfs-file-systems.section.md

     

       42
        
       ```

+9 -9

nixos/doc/manual/configuration/networking.chapter.md

···

       3
        
       This section describes how to configure networking components

     

       4
        
       on your NixOS machine.

     

       5
        
       

     

       6
       -
       ```{=docbook}

     

       7
       -
       <xi:include href="network-manager.section.xml" />

     

       8
       -
       <xi:include href="ssh.section.xml" />

     

       9
       -
       <xi:include href="ipv4-config.section.xml" />

     

       10
       -
       <xi:include href="ipv6-config.section.xml" />

     

       11
       -
       <xi:include href="firewall.section.xml" />

     

       12
       -
       <xi:include href="wireless.section.xml" />

     

       13
       -
       <xi:include href="ad-hoc-network-config.section.xml" />

     

       14
       -
       <xi:include href="renaming-interfaces.section.xml" />

     

       15
        
       ```

     

       16
        
       <!-- TODO: OpenVPN, NAT -->

···

       3
        
       This section describes how to configure networking components

     

       4
        
       on your NixOS machine.

     

       5
        
       

     

       6
       +
       ```{=include=} sections

     

       7
       +
       network-manager.section.md

     

       8
       +
       ssh.section.md

     

       9
       +
       ipv4-config.section.md

     

       10
       +
       ipv6-config.section.md

     

       11
       +
       firewall.section.md

     

       12
       +
       wireless.section.md

     

       13
       +
       ad-hoc-network-config.section.md

     

       14
       +
       renaming-interfaces.section.md

     

       15
        
       ```

     

       16
        
       <!-- TODO: OpenVPN, NAT -->

+3 -3

nixos/doc/manual/configuration/package-mgmt.chapter.md

···

       12
        
           `nix-env` command. This style allows mixing packages from different

     

       13
        
           Nixpkgs versions. It's the only choice for non-root users.

     

       14
        
       

     

       15
       -
       ```{=docbook}

     

       16
       -
       <xi:include href="declarative-packages.section.xml" />

     

       17
       -
       <xi:include href="ad-hoc-packages.section.xml" />

     

       18
        
       ```

···

       12
        
           `nix-env` command. This style allows mixing packages from different

     

       13
        
           Nixpkgs versions. It's the only choice for non-root users.

     

       14
        
       

     

       15
       +
       ```{=include=} sections

     

       16
       +
       declarative-packages.section.md

     

       17
       +
       ad-hoc-packages.section.md

     

       18
        
       ```

+12 -12

nixos/doc/manual/configuration/profiles.chapter.md

···

       19
        
       What follows is a brief explanation on the purpose and use-case for each

     

       20
        
       profile. Detailing each option configured by each one is out of scope.

     

       21
        
       

     

       22
       -
       ```{=docbook}

     

       23
       -
       <xi:include href="profiles/all-hardware.section.xml" />

     

       24
       -
       <xi:include href="profiles/base.section.xml" />

     

       25
       -
       <xi:include href="profiles/clone-config.section.xml" />

     

       26
       -
       <xi:include href="profiles/demo.section.xml" />

     

       27
       -
       <xi:include href="profiles/docker-container.section.xml" />

     

       28
       -
       <xi:include href="profiles/graphical.section.xml" />

     

       29
       -
       <xi:include href="profiles/hardened.section.xml" />

     

       30
       -
       <xi:include href="profiles/headless.section.xml" />

     

       31
       -
       <xi:include href="profiles/installation-device.section.xml" />

     

       32
       -
       <xi:include href="profiles/minimal.section.xml" />

     

       33
       -
       <xi:include href="profiles/qemu-guest.section.xml" />

     

       34
        
       ```

···

       19
        
       What follows is a brief explanation on the purpose and use-case for each

     

       20
        
       profile. Detailing each option configured by each one is out of scope.

     

       21
        
       

     

       22
       +
       ```{=include=} sections

     

       23
       +
       profiles/all-hardware.section.md

     

       24
       +
       profiles/base.section.md

     

       25
       +
       profiles/clone-config.section.md

     

       26
       +
       profiles/demo.section.md

     

       27
       +
       profiles/docker-container.section.md

     

       28
       +
       profiles/graphical.section.md

     

       29
       +
       profiles/hardened.section.md

     

       30
       +
       profiles/headless.section.md

     

       31
       +
       profiles/installation-device.section.md

     

       32
       +
       profiles/minimal.section.md

     

       33
       +
       profiles/qemu-guest.section.md

     

       34
        
       ```

+18 -27

nixos/doc/manual/default.nix

···

       143
        
           ''

     

       144
        
             cp -r --no-preserve=all $inputs/* .

     

       145
        
       

     

       146
       -
             declare -a convert_args

     

       147
       -
             while read -r mf; do

     

       148
       -
               if [[ "$mf" = *.chapter.md ]]; then

     

       149
       -
                 convert_args+=("--chapter")

     

       150
       -
               else

     

       151
       -
                 convert_args+=("--section")

     

       152
       -
               fi

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       153
        
       

     

       154
       -
               convert_args+=("from_md/''${mf%.md}.xml" "$mf")

     

       155
       -
             done < <(find . -type f -name '*.md')

     

       156
       -
       

     

       157
       -
             nixos-render-docs manual docbook-fragment \

     

       158
        
               --manpage-urls ${manpageUrls} \

     

       159
       -
               "''${convert_args[@]}"

     

       160
       -
       

     

       161
       -
             mkdir ./generated

     

       162
       -
             ln -s ${optionsDoc.optionsDocBook} ./generated/options-db.xml

     

       163
       -
             ln -s ${testOptionsDoc.optionsDocBook} ./generated/test-options-db.xml

     

       164
       -
             printf "%s" "${version}" > ./generated/version

     

       165
       -
             chmod -R u+w .

     

       166
       -
       

     

       167
       -
             nixos-render-docs manual docbook-section \

     

       168
       -
               --manpage-urls ${manpageUrls} \

     

       169
       -
               ./generated/modules.xml \

     

       170
       -
               --section \

     

       171
       -
                 --section-id modules \

     

       172
       -
                 --chapters ${lib.concatMapStrings (p: "${p.value} ") config.meta.doc}

     

       173
       -
       

     

       174
       -
             xmllint --xinclude --output ./manual-combined.xml ./manual.xml

     

       175
        
       

     

       176
        
             ${linterFunctions}

     

       177

···

       143
        
           ''

     

       144
        
             cp -r --no-preserve=all $inputs/* .

     

       145
        
       

     

       146
       +
             substituteInPlace ./manual.md \

     

       147
       +
               --replace '@NIXOS_VERSION@' "${version}"

     

       148
       +
             substituteInPlace ./configuration/configuration.md \

     

       149
       +
               --replace \

     

       150
       +
                   '@MODULE_CHAPTERS@' \

     

       151
       +
                   ${lib.escapeShellArg (lib.concatMapStringsSep "\n" (p: "${p.value}") config.meta.doc)}

     

       152
       +
             substituteInPlace ./nixos-options.md \

     

       153
       +
               --replace \

     

       154
       +
                 '@NIXOS_OPTIONS_JSON@' \

     

       155
       +
                 ${optionsDoc.optionsJSON}/share/doc/nixos/options.json

     

       156
       +
             substituteInPlace ./development/writing-nixos-tests.section.md \

     

       157
       +
               --replace \

     

       158
       +
                 '@NIXOS_TEST_OPTIONS_JSON@' \

     

       159
       +
                 ${testOptionsDoc.optionsJSON}/share/doc/nixos/options.json

     

       160
        
       

     

       161
       +
             nixos-render-docs manual docbook \

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       162
        
               --manpage-urls ${manpageUrls} \

     

       163
       +
               --revision ${lib.escapeShellArg revision} \

     

       164
       +
               ./manual.md \

     

       165
       +
               ./manual-combined.xml

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       166
        
       

     

       167
        
             ${linterFunctions}

     

       168

+14

nixos/doc/manual/development/development.md

···

       1
       +
       # Development {#ch-development}

     

       2
       +
       

     

       3
       +
       This chapter describes how you can modify and extend NixOS.

     

       4
       +
       

     

       5
       +
       ```{=include=} chapters

     

       6
       +
       sources.chapter.md

     

       7
       +
       writing-modules.chapter.md

     

       8
       +
       building-parts.chapter.md

     

       9
       +
       bootspec.chapter.md

     

       10
       +
       what-happens-during-a-system-switch.chapter.md

     

       11
       +
       writing-documentation.chapter.md

     

       12
       +
       nixos-tests.chapter.md

     

       13
       +
       testing-installer.chapter.md

     

       14
       +
       ```

-20

nixos/doc/manual/development/development.xml

···

       1
       -
       <part   xmlns="http://docbook.org/ns/docbook"

     

       2
       -
               xmlns:xlink="http://www.w3.org/1999/xlink"

     

       3
       -
               xmlns:xi="http://www.w3.org/2001/XInclude"

     

       4
       -
               version="5.0"

     

       5
       -
               xml:id="ch-development">

     

       6
       -
        <title>Development</title>

     

       7
       -
        <partintro xml:id="ch-development-intro">

     

       8
       -
         <para>

     

       9
       -
          This chapter describes how you can modify and extend NixOS.

     

       10
       -
         </para>

     

       11
       -
        </partintro>

     

       12
       -
        <xi:include href="../from_md/development/sources.chapter.xml" />

     

       13
       -
        <xi:include href="../from_md/development/writing-modules.chapter.xml" />

     

       14
       -
        <xi:include href="../from_md/development/building-parts.chapter.xml" />

     

       15
       -
        <xi:include href="../from_md/development/bootspec.chapter.xml" />

     

       16
       -
        <xi:include href="../from_md/development/what-happens-during-a-system-switch.chapter.xml" />

     

       17
       -
        <xi:include href="../from_md/development/writing-documentation.chapter.xml" />

     

       18
       -
        <xi:include href="../from_md/development/nixos-tests.chapter.xml" />

     

       19
       -
        <xi:include href="../from_md/development/testing-installer.chapter.xml" />

     

       20
       -
       </part>

+5 -5

nixos/doc/manual/development/nixos-tests.chapter.md

···

       5
        
       (using Nix) by a testing framework that automatically starts one or more

     

       6
        
       virtual machines containing the NixOS system(s) required for the test.

     

       7
        
       

     

       8
       -
       ```{=docbook}

     

       9
       -
       <xi:include href="writing-nixos-tests.section.xml" />

     

       10
       -
       <xi:include href="running-nixos-tests.section.xml" />

     

       11
       -
       <xi:include href="running-nixos-tests-interactively.section.xml" />

     

       12
       -
       <xi:include href="linking-nixos-tests-to-packages.section.xml" />

     

       13
        
       ```

···

       5
        
       (using Nix) by a testing framework that automatically starts one or more

     

       6
        
       virtual machines containing the NixOS system(s) required for the test.

     

       7
        
       

     

       8
       +
       ```{=include=} sections

     

       9
       +
       writing-nixos-tests.section.md

     

       10
       +
       running-nixos-tests.section.md

     

       11
       +
       running-nixos-tests-interactively.section.md

     

       12
       +
       linking-nixos-tests-to-packages.section.md

     

       13
        
       ```

+3 -3

nixos/doc/manual/development/what-happens-during-a-system-switch.chapter.md

···

       47
        
       with our units or the activation script. For this reason, these topics are

     

       48
        
       explained in the next sections.

     

       49
        
       

     

       50
       -
       ```{=docbook}

     

       51
       -
       <xi:include href="unit-handling.section.xml" />

     

       52
       -
       <xi:include href="activation-script.section.xml" />

     

       53
        
       ```

···

       47
        
       with our units or the activation script. For this reason, these topics are

     

       48
        
       explained in the next sections.

     

       49
        
       

     

       50
       +
       ```{=include=} sections

     

       51
       +
       unit-handling.section.md

     

       52
       +
       activation-script.section.md

     

       53
        
       ```

+1 -1

nixos/doc/manual/development/writing-documentation.chapter.md

···

       83
        
       

     

       84
        
       ## Adding a Topic to the Book {#sec-writing-docs-adding-a-topic}

     

       85
        
       

     

       86
       -
       Open the parent XML file and add an `xi:include` element to the list of

     

       87
        
       chapters with the file name of the topic that you created. If you

     

       88
        
       created a `section`, you add the file to the `chapter` file. If you created

     

       89
        
       a `chapter`, you add the file to the `part` file.

···

       83
        
       

     

       84
        
       ## Adding a Topic to the Book {#sec-writing-docs-adding-a-topic}

     

       85
        
       

     

       86
       +
       Open the parent CommonMark file and add a line to the list of

     

       87
        
       chapters with the file name of the topic that you created. If you

     

       88
        
       created a `section`, you add the file to the `chapter` file. If you created

     

       89
        
       a `chapter`, you add the file to the `part` file.

+10 -10

nixos/doc/manual/development/writing-modules.chapter.md

···

       189
        
       ```

     

       190
        
       :::

     

       191
        
       

     

       192
       -
       ```{=docbook}

     

       193
       -
       <xi:include href="option-declarations.section.xml" />

     

       194
       -
       <xi:include href="option-types.section.xml" />

     

       195
       -
       <xi:include href="option-def.section.xml" />

     

       196
       -
       <xi:include href="assertions.section.xml" />

     

       197
       -
       <xi:include href="meta-attributes.section.xml" />

     

       198
       -
       <xi:include href="importing-modules.section.xml" />

     

       199
       -
       <xi:include href="replace-modules.section.xml" />

     

       200
       -
       <xi:include href="freeform-modules.section.xml" />

     

       201
       -
       <xi:include href="settings-options.section.xml" />

     

       202
        
       ```

···

       189
        
       ```

     

       190
        
       :::

     

       191
        
       

     

       192
       +
       ```{=include=} sections

     

       193
       +
       option-declarations.section.md

     

       194
       +
       option-types.section.md

     

       195
       +
       option-def.section.md

     

       196
       +
       assertions.section.md

     

       197
       +
       meta-attributes.section.md

     

       198
       +
       importing-modules.section.md

     

       199
       +
       replace-modules.section.md

     

       200
       +
       freeform-modules.section.md

     

       201
       +
       settings-options.section.md

     

       202
        
       ```

+4 -2

nixos/doc/manual/development/writing-nixos-tests.section.md

···

       470
        
       

     

       471
        
       The following options can be used when writing tests.

     

       472
        
       

     

       473
       -
       ```{=docbook}

     

       474
       -
       <xi:include href="../../generated/test-options-db.xml" xpointer="test-options-list"/>

     

       0
        
       
     

       0
        
       
     

       475
        
       ```

···

       470
        
       

     

       471
        
       The following options can be used when writing tests.

     

       472
        
       

     

       473
       +
       ```{=include=} options

     

       474
       +
       id-prefix: test-opt-

     

       475
       +
       list-id: test-options-list

     

       476
       +
       source: @NIXOS_TEST_OPTIONS_JSON@

     

       477
        
       ```

+11

nixos/doc/manual/installation/installation.md

···

       1
       +
       # Installation {#ch-installation}

     

       2
       +
       

     

       3
       +
       This section describes how to obtain, install, and configure NixOS for first-time use.

     

       4
       +
       

     

       5
       +
       ```{=include=} chapters

     

       6
       +
       obtaining.chapter.md

     

       7
       +
       installing.chapter.md

     

       8
       +
       changing-config.chapter.md

     

       9
       +
       upgrading.chapter.md

     

       10
       +
       building-nixos.chapter.md

     

       11
       +
       ```

-18

nixos/doc/manual/installation/installation.xml

···

       1
       -
       <part xmlns="http://docbook.org/ns/docbook"

     

       2
       -
             xmlns:xlink="http://www.w3.org/1999/xlink"

     

       3
       -
             xmlns:xi="http://www.w3.org/2001/XInclude"

     

       4
       -
             version="5.0"

     

       5
       -
             xml:id="ch-installation">

     

       6
       -
        <title>Installation</title>

     

       7
       -
        <partintro xml:id="ch-installation-intro">

     

       8
       -
         <para>

     

       9
       -
          This section describes how to obtain, install, and configure NixOS for

     

       10
       -
          first-time use.

     

       11
       -
         </para>

     

       12
       -
        </partintro>

     

       13
       -
        <xi:include href="../from_md/installation/obtaining.chapter.xml" />

     

       14
       -
        <xi:include href="../from_md/installation/installing.chapter.xml" />

     

       15
       -
        <xi:include href="../from_md/installation/changing-config.chapter.xml" />

     

       16
       -
        <xi:include href="../from_md/installation/upgrading.chapter.xml" />

     

       17
       -
        <xi:include href="../from_md/installation/building-nixos.chapter.xml" />

     

       18
       -
       </part>

+7 -7

nixos/doc/manual/installation/installing.chapter.md

···

       602
        
       

     

       603
        
       ## Additional installation notes {#sec-installation-additional-notes}

     

       604
        
       

     

       605
       -
       ```{=docbook}

     

       606
       -
       <xi:include href="installing-usb.section.xml" />

     

       607
       -
       <xi:include href="installing-pxe.section.xml" />

     

       608
       -
       <xi:include href="installing-kexec.section.xml" />

     

       609
       -
       <xi:include href="installing-virtualbox-guest.section.xml" />

     

       610
       -
       <xi:include href="installing-from-other-distro.section.xml" />

     

       611
       -
       <xi:include href="installing-behind-a-proxy.section.xml" />

     

       612
        
       ```

···

       602
        
       

     

       603
        
       ## Additional installation notes {#sec-installation-additional-notes}

     

       604
        
       

     

       605
       +
       ```{=include=} sections

     

       606
       +
       installing-usb.section.md

     

       607
       +
       installing-pxe.section.md

     

       608
       +
       installing-kexec.section.md

     

       609
       +
       installing-virtualbox-guest.section.md

     

       610
       +
       installing-from-other-distro.section.md

     

       611
       +
       installing-behind-a-proxy.section.md

     

       612
        
       ```

+53

nixos/doc/manual/manual.md

···

       1
       +
       # NixOS Manual {#book-nixos-manual}

     

       2
       +
       ## Version @NIXOS_VERSION@

     

       3
       +
       

     

       4
       +
       <!--

     

       5
       +
         this is the top-level structure file for the nixos manual.

     

       6
       +
       

     

       7
       +
         the manual structure extends the nixpkgs commonmark further with include

     

       8
       +
         blocks to allow better organization of input text. there are six types of

     

       9
       +
         include blocks: preface, parts, chapters, sections, appendix, and options.

     

       10
       +
         each type except `options`` corresponds to the docbook elements of (roughly)

     

       11
       +
         the same name, and can itself can further include blocks to denote its

     

       12
       +
         substructure.

     

       13
       +
       

     

       14
       +
         non-`options`` include blocks are fenced code blocks that list a number of

     

       15
       +
         files to include, in the form

     

       16
       +
       

     

       17
       +
            ```{=include=} <type>

     

       18
       +
            <file-name-1>

     

       19
       +
            <file-name-2>

     

       20
       +
            <...>

     

       21
       +
            ```

     

       22
       +
       

     

       23
       +
         `options` include blocks do not list file names but contain a list of key-value

     

       24
       +
         pairs that describe the options to be included and how to convert them into

     

       25
       +
         elements of the manual output type:

     

       26
       +
       

     

       27
       +
             ```{=include=} options

     

       28
       +
             id-prefix: <options id prefix>

     

       29
       +
             list-id: <variable list element id>

     

       30
       +
             source: <path to options.json>

     

       31
       +
             ```

     

       32
       +
       

     

       33
       +
       -->

     

       34
       +
       

     

       35
       +
       ```{=include=} preface

     

       36
       +
       preface.md

     

       37
       +
       ```

     

       38
       +
       

     

       39
       +
       ```{=include=} parts

     

       40
       +
       installation/installation.md

     

       41
       +
       configuration/configuration.md

     

       42
       +
       administration/running.md

     

       43
       +
       development/development.md

     

       44
       +
       ```

     

       45
       +
       

     

       46
       +
       ```{=include=} chapters

     

       47
       +
       contributing-to-this-manual.chapter.md

     

       48
       +
       ```

     

       49
       +
       

     

       50
       +
       ```{=include=} appendix

     

       51
       +
       nixos-options.md

     

       52
       +
       release-notes/release-notes.md

     

       53
       +
       ```

-23

nixos/doc/manual/manual.xml

···

       1
       -
       <book xmlns="http://docbook.org/ns/docbook"

     

       2
       -
             xmlns:xlink="http://www.w3.org/1999/xlink"

     

       3
       -
             xmlns:xi="http://www.w3.org/2001/XInclude"

     

       4
       -
             version="5.0"

     

       5
       -
             xml:id="book-nixos-manual">

     

       6
       -
        <info>

     

       7
       -
         <title>NixOS Manual</title>

     

       8
       -
         <subtitle>Version <xi:include href="./generated/version" parse="text" />

     

       9
       -
         </subtitle>

     

       10
       -
        </info>

     

       11
       -
        <xi:include href="preface.xml" />

     

       12
       -
        <xi:include href="installation/installation.xml" />

     

       13
       -
        <xi:include href="configuration/configuration.xml" />

     

       14
       -
        <xi:include href="administration/running.xml" />

     

       15
       -
        <xi:include href="development/development.xml" />

     

       16
       -
        <xi:include href="./from_md/contributing-to-this-manual.chapter.xml" />

     

       17
       -
        <appendix xml:id="ch-options">

     

       18
       -
         <title>Configuration Options</title>

     

       19
       -
         <xi:include href="./generated/options-db.xml"

     

       20
       -
                       xpointer="configuration-variable-list" />

     

       21
       -
        </appendix>

     

       22
       -
        <xi:include href="release-notes/release-notes.xml" />

     

       23
       -
       </book>

nixos/doc/manual/nixos-options.md

···

       1
       +
       # Configuration Options {#ch-options}

     

       2
       +
       

     

       3
       +
       ```{=include=} options

     

       4
       +
       id-prefix: opt-

     

       5
       +
       list-id: configuration-variable-list

     

       6
       +
       source: @NIXOS_OPTIONS_JSON@

     

       7
       +
       ```

+11

nixos/doc/manual/preface.md

···

       1
       +
       # Preface {#preface}

     

       2
       +
       

     

       3
       +
       This manual describes how to install, use and extend NixOS, a Linux distribution based on the purely functional package management system [Nix](https://nixos.org/nix), that is composed using modules and packages defined in the [Nixpkgs](https://nixos.org/nixpkgs) project.

     

       4
       +
       

     

       5
       +
       Additional information regarding the Nix package manager and the Nixpkgs project can be found in respectively the [Nix manual](https://nixos.org/nix/manual) and the [Nixpkgs manual](https://nixos.org/nixpkgs/manual).

     

       6
       +
       

     

       7
       +
       If you encounter problems, please report them on the [`Discourse`](https://discourse.nixos.org), the [Matrix room](https://matrix.to/#nix:nixos.org), or on the [`#nixos` channel on Libera.Chat](irc://irc.libera.chat/#nixos). Alternatively, consider [contributing to this manual](#chap-contributing). Bugs should be reported in [NixOS’ GitHub issue tracker](https://github.com/NixOS/nixpkgs/issues).

     

       8
       +
       

     

       9
       +
       ::: {.note}

     

       10
       +
       Commands prefixed with `#` have to be run as root, either requiring to login as root user or temporarily switching to it using `sudo` for example.

     

       11
       +
       :::

-42

nixos/doc/manual/preface.xml

···

       1
       -
       <preface xmlns="http://docbook.org/ns/docbook"

     

       2
       -
                xmlns:xlink="http://www.w3.org/1999/xlink"

     

       3
       -
                xml:id="preface">

     

       4
       -
        <title>Preface</title>

     

       5
       -
        <para>

     

       6
       -
         This manual describes how to install, use and extend NixOS, a Linux

     

       7
       -
         distribution based on the purely functional package management system

     

       8
       -
         <link xlink:href="https://nixos.org/nix">Nix</link>, that is composed

     

       9
       -
         using modules and packages defined in the

     

       10
       -
         <link xlink:href="https://nixos.org/nixpkgs">Nixpkgs</link> project.

     

       11
       -
        </para>

     

       12
       -
        <para>

     

       13
       -
         Additional information regarding the Nix package manager and the Nixpkgs

     

       14
       -
         project can be found in respectively the

     

       15
       -
         <link xlink:href="https://nixos.org/nix/manual">Nix manual</link> and the

     

       16
       -
         <link xlink:href="https://nixos.org/nixpkgs/manual">Nixpkgs manual</link>.

     

       17
       -
        </para>

     

       18
       -
        <para>

     

       19
       -
         If you encounter problems, please report them on the

     

       20
       -
         <literal

     

       21
       -
          xlink:href="https://discourse.nixos.org">Discourse</literal>,

     

       22
       -
         the <link

     

       23
       -
          xlink:href="https://matrix.to/#nix:nixos.org">Matrix room</link>,

     

       24
       -
         or on the <link

     

       25
       -
          xlink:href="irc://irc.libera.chat/#nixos">

     

       26
       -
         <literal>#nixos</literal> channel on Libera.Chat</link>.

     

       27
       -
         Alternatively, consider <link

     

       28
       -
          xlink:href="#chap-contributing">

     

       29
       -
          contributing to this manual</link>. Bugs should be

     

       30
       -
         reported in

     

       31
       -
         <link

     

       32
       -
          xlink:href="https://github.com/NixOS/nixpkgs/issues">NixOS’

     

       33
       -
         GitHub issue tracker</link>.

     

       34
       -
        </para>

     

       35
       -
        <note>

     

       36
       -
         <para>

     

       37
       -
          Commands prefixed with <literal>#</literal> have to be run as root, either

     

       38
       -
          requiring to login as root user or temporarily switching to it using

     

       39
       -
          <literal>sudo</literal> for example.

     

       40
       -
         </para>

     

       41
       -
        </note>

     

       42
       -
       </preface>

+25

nixos/doc/manual/release-notes/release-notes.md

···

       1
       +
       # Release Notes {#ch-release-notes}

     

       2
       +
       

     

       3
       +
       This section lists the release notes for each stable version of NixOS and current unstable revision.

     

       4
       +
       

     

       5
       +
       ```{=include=} sections

     

       6
       +
       rl-2305.section.md

     

       7
       +
       rl-2211.section.md

     

       8
       +
       rl-2205.section.md

     

       9
       +
       rl-2111.section.md

     

       10
       +
       rl-2105.section.md

     

       11
       +
       rl-2009.section.md

     

       12
       +
       rl-2003.section.md

     

       13
       +
       rl-1909.section.md

     

       14
       +
       rl-1903.section.md

     

       15
       +
       rl-1809.section.md

     

       16
       +
       rl-1803.section.md

     

       17
       +
       rl-1709.section.md

     

       18
       +
       rl-1703.section.md

     

       19
       +
       rl-1609.section.md

     

       20
       +
       rl-1603.section.md

     

       21
       +
       rl-1509.section.md

     

       22
       +
       rl-1412.section.md

     

       23
       +
       rl-1404.section.md

     

       24
       +
       rl-1310.section.md

     

       25
       +
       ```

-30

nixos/doc/manual/release-notes/release-notes.xml

···

       1
       -
       <appendix xmlns="http://docbook.org/ns/docbook"

     

       2
       -
                 xmlns:xlink="http://www.w3.org/1999/xlink"

     

       3
       -
                 xmlns:xi="http://www.w3.org/2001/XInclude"

     

       4
       -
                 version="5.0"

     

       5
       -
                 xml:id="ch-release-notes">

     

       6
       -
        <title>Release Notes</title>

     

       7
       -
        <para>

     

       8
       -
         This section lists the release notes for each stable version of NixOS and

     

       9
       -
         current unstable revision.

     

       10
       -
        </para>

     

       11
       -
        <xi:include href="../from_md/release-notes/rl-2305.section.xml" />

     

       12
       -
        <xi:include href="../from_md/release-notes/rl-2211.section.xml" />

     

       13
       -
        <xi:include href="../from_md/release-notes/rl-2205.section.xml" />

     

       14
       -
        <xi:include href="../from_md/release-notes/rl-2111.section.xml" />

     

       15
       -
        <xi:include href="../from_md/release-notes/rl-2105.section.xml" />

     

       16
       -
        <xi:include href="../from_md/release-notes/rl-2009.section.xml" />

     

       17
       -
        <xi:include href="../from_md/release-notes/rl-2003.section.xml" />

     

       18
       -
        <xi:include href="../from_md/release-notes/rl-1909.section.xml" />

     

       19
       -
        <xi:include href="../from_md/release-notes/rl-1903.section.xml" />

     

       20
       -
        <xi:include href="../from_md/release-notes/rl-1809.section.xml" />

     

       21
       -
        <xi:include href="../from_md/release-notes/rl-1803.section.xml" />

     

       22
       -
        <xi:include href="../from_md/release-notes/rl-1709.section.xml" />

     

       23
       -
        <xi:include href="../from_md/release-notes/rl-1703.section.xml" />

     

       24
       -
        <xi:include href="../from_md/release-notes/rl-1609.section.xml" />

     

       25
       -
        <xi:include href="../from_md/release-notes/rl-1603.section.xml" />

     

       26
       -
        <xi:include href="../from_md/release-notes/rl-1509.section.xml" />

     

       27
       -
        <xi:include href="../from_md/release-notes/rl-1412.section.xml" />

     

       28
       -
        <xi:include href="../from_md/release-notes/rl-1404.section.xml" />

     

       29
       -
        <xi:include href="../from_md/release-notes/rl-1310.section.xml" />

     

       30
       -
       </appendix>

+162 -137

pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manual.py

···

       2
        
       import json

     

       3
        
       

     

       4
        
       from abc import abstractmethod

     

       5
       -
       from collections.abc import MutableMapping, Sequence

     

       6
        
       from pathlib import Path

     

       7
        
       from typing import Any, cast, NamedTuple, Optional, Union

     

       8
        
       from xml.sax.saxutils import escape, quoteattr

     

       0
        
       
     

       0
        
       
     

       9
        
       from markdown_it.token import Token

     

       10
        
       from markdown_it.utils import OptionsDict

     

       11
        
       

     

       12
       -
       from .docbook import DocBookRenderer

     

       0
        
       
     

       13
        
       from .md import Converter

     

       14
        
       

     

       15
       -
       class RenderedSection:

     

       16
       -
           id: Optional[str]

     

       17
       -
           chapters: list[str]

     

       18
        
       

     

       19
       -
           def __init__(self, id: Optional[str]) -> None:

     

       20
       -
               self.id = id

     

       21
       -
               self.chapters = []

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       22
        
       

     

       23
       -
       class BaseConverter(Converter):

     

       24
       -
           _sections: list[RenderedSection]

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       25
        
       

     

       26
       -
           def __init__(self, manpage_urls: dict[str, str]):

     

       27
       -
               super().__init__(manpage_urls)

     

       28
       -
               self._sections = []

     

       29
       -
       

     

       30
       -
           def add_section(self, id: Optional[str], chapters: list[Path]) -> None:

     

       31
       -
               self._sections.append(RenderedSection(id))

     

       32
       -
               for chpath in chapters:

     

       33
       -
                   try:

     

       34
       -
                       with open(chpath, 'r') as f:

     

       35
       -
                           self._md.renderer._title_seen = False # type: ignore[attr-defined]

     

       36
       -
                           self._sections[-1].chapters.append(self._render(f.read()))

     

       37
       -
                   except Exception as e:

     

       38
       -
                       raise RuntimeError(f"failed to render manual chapter {chpath}") from e

     

       39
       -
       

     

       40
       -
           @abstractmethod

     

       41
       -
           def finalize(self) -> str: raise NotImplementedError()

     

       42
        
       

     

       43
       -
       class ManualDocBookRenderer(DocBookRenderer):

     

       44
       -
           # needed to check correctness of chapters.

     

       45
       -
           # we may want to use front matter instead of this kind of heuristic.

     

       46
       -
           _title_seen = False

     

       47
        
       

     

       48
        
           def _heading_tag(self, token: Token, tokens: Sequence[Token], i: int, options: OptionsDict,

     

       49
        
                            env: MutableMapping[str, Any]) -> tuple[str, dict[str, str]]:

     

       50
        
               (tag, attrs) = super()._heading_tag(token, tokens, i, options, env)

     

       51
       -
               if self._title_seen:

     

       52
       -
                   if token.tag == 'h1':

     

       53
       -
                       assert token.map is not None

     

       54
       -
                       raise RuntimeError(

     

       55
       -
                           "only one title heading (# [text...]) allowed per manual chapter "

     

       56
       -
                           f"but found a second in lines [{token.map[0]}..{token.map[1]}]. "

     

       57
       -
                           "please remove all such headings except the first, split your "

     

       58
       -
                           "chapters, or demote the subsequent headings to (##) or lower.",

     

       59
       -
                           token)

     

       60
        
                   return (tag, attrs)

     

       61
       -
               self._title_seen = True

     

       62
       -
               return ("chapter", attrs | {

     

       63
        
                   'xmlns': "http://docbook.org/ns/docbook",

     

       64
        
                   'xmlns:xlink': "http://www.w3.org/1999/xlink",

     

       65
        
               })

     

       66
        
       

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       67
        
           # TODO minimize docbook diffs with existing conversions. remove soon.

     

       68
        
           def paragraph_open(self, token: Token, tokens: Sequence[Token], i: int, options: OptionsDict,

     

       69
        
                              env: MutableMapping[str, Any]) -> str:

     
···

       76
        
               return f"<programlisting>\n{escape(token.content)}</programlisting>"

     

       77
        
           def fence(self, token: Token, tokens: Sequence[Token], i: int, options: OptionsDict,

     

       78
        
                     env: MutableMapping[str, Any]) -> str:

     

       79
       -
               # HACK for temporarily being able to replace md-to-db.sh. pandoc used this syntax to

     

       80
       -
               # allow md files to inject arbitrary docbook, and manual chapters use it.

     

       81
       -
               if token.info == '{=docbook}':

     

       82
       -
                   return token.content

     

       83
        
               info = f" language={quoteattr(token.info)}" if token.info != "" else ""

     

       84
        
               return f"<programlisting{info}>\n{escape(token.content)}</programlisting>"

     

       85
        
       

     

       86
       -
       class DocBookSectionConverter(BaseConverter):

     

       87
       -
           __renderer__ = ManualDocBookRenderer

     

       0
        
       
     

       0
        
       
     

       88
        
       

     

       89
       -
           def finalize(self) -> str:

     

       90
       -
               result = []

     

       91
       -
       

     

       92
       -
               for section in self._sections:

     

       93
       -
                   id = "id=" + quoteattr(section.id) if section.id is not None else ""

     

       94
       -
                   result.append(f'<section {id}>')

     

       95
       -
                   result += section.chapters

     

       96
       -
                   result.append(f'</section>')

     

       97
       -
       

     

       98
       -
               return "\n".join(result)

     

       99
        
       

     

       100
       -
       class ManualFragmentDocBookRenderer(ManualDocBookRenderer):

     

       101
       -
           _tag: str = "chapter"

     

       0
        
       
     

       102
        
       

     

       103
       -
           def _heading_tag(self, token: Token, tokens: Sequence[Token], i: int, options: OptionsDict,

     

       104
       -
                            env: MutableMapping[str, Any]) -> tuple[str, dict[str, str]]:

     

       105
       -
               (tag, attrs) = super()._heading_tag(token, tokens, i, options, env)

     

       106
       -
               if token.tag == 'h1':

     

       107
       -
                   return (self._tag, attrs | { 'xmlns:xi': "http://www.w3.org/2001/XInclude" })

     

       108
       -
               return (tag, attrs)

     

       109
       -
       

     

       110
       -
       class DocBookFragmentConverter(Converter):

     

       111
       -
           __renderer__ = ManualFragmentDocBookRenderer

     

       112
       -
       

     

       113
       -
           def convert(self, file: Path, tag: str) -> str:

     

       114
       -
               assert isinstance(self._md.renderer, ManualFragmentDocBookRenderer)

     

       115
        
               try:

     

       116
        
                   with open(file, 'r') as f:

     

       117
       -
                       self._md.renderer._title_seen = False

     

       118
       -
                       self._md.renderer._tag = tag

     

       119
        
                       return self._render(f.read())

     

       120
        
               except Exception as e:

     

       121
       -
                   raise RuntimeError(f"failed to render manual {tag} {file}") from e

     

       122
        
       

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       123
        
       

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       124
        
       

     

       125
       -
       class Section:

     

       126
       -
           id: Optional[str] = None

     

       127
       -
           chapters: list[str]

     

       128
        
       

     

       129
       -
           def __init__(self) -> None:

     

       130
       -
               self.chapters = []

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       131
        
       

     

       132
       -
       class SectionAction(argparse.Action):

     

       133
       -
           def __call__(self, parser: argparse.ArgumentParser, ns: argparse.Namespace,

     

       134
       -
                        values: Union[str, Sequence[Any], None], opt_str: Optional[str] = None) -> None:

     

       135
       -
               sections = getattr(ns, self.dest)

     

       136
       -
               if sections is None: sections = []

     

       137
       -
               sections.append(Section())

     

       138
       -
               setattr(ns, self.dest, sections)

     

       0
        
       
     

       139
        
       

     

       140
       -
       class SectionIDAction(argparse.Action):

     

       141
       -
           def __call__(self, parser: argparse.ArgumentParser, ns: argparse.Namespace,

     

       142
       -
                        values: Union[str, Sequence[Any], None], opt_str: Optional[str] = None) -> None:

     

       143
       -
               sections = getattr(ns, self.dest)

     

       144
       -
               if sections is None: raise argparse.ArgumentError(self, "no active section")

     

       145
       -
               sections[-1].id = cast(str, values)

     

       146
        
       

     

       147
       -
       class ChaptersAction(argparse.Action):

     

       148
       -
           def __call__(self, parser: argparse.ArgumentParser, ns: argparse.Namespace,

     

       149
       -
                        values: Union[str, Sequence[Any], None], opt_str: Optional[str] = None) -> None:

     

       150
       -
               sections = getattr(ns, self.dest)

     

       151
       -
               if sections is None: raise argparse.ArgumentError(self, "no active section")

     

       152
       -
               sections[-1].chapters.extend(map(Path, cast(Sequence[str], values)))

     

       153
        
       

     

       154
       -
       class SingleFileAction(argparse.Action):

     

       155
       -
           def __call__(self, parser: argparse.ArgumentParser, ns: argparse.Namespace,

     

       156
       -
                        values: Union[str, Sequence[Any], None], opt_str: Optional[str] = None) -> None:

     

       157
       -
               assert isinstance(values, Sequence)

     

       158
       -
               chapters = getattr(ns, self.dest) or []

     

       159
       -
               chapters.append((Path(values[0]), Path(values[1])))

     

       160
       -
               setattr(ns, self.dest, chapters)

     

       161
       -
       

     

       162
       -
       def _build_cli_db_section(p: argparse.ArgumentParser) -> None:

     

       163
       -
           p.add_argument('--manpage-urls', required=True)

     

       164
       -
           p.add_argument("outfile")

     

       165
       -
           p.add_argument("--section", dest="contents", action=SectionAction, nargs=0)

     

       166
       -
           p.add_argument("--section-id", dest="contents", action=SectionIDAction)

     

       167
       -
           p.add_argument("--chapters", dest="contents", action=ChaptersAction, nargs='+')

     

       168
       -
       

     

       169
       -
       def _build_cli_db_fragment(p: argparse.ArgumentParser) -> None:

     

       170
        
           p.add_argument('--manpage-urls', required=True)

     

       171
       -
           p.add_argument("--chapter", action=SingleFileAction, required=True, nargs=2)

     

       172
       -
           p.add_argument("--section", action=SingleFileAction, required=True, nargs=2)

     

       0
        
       
     

       173
        
       

     

       174
       -
       def _run_cli_db_section(args: argparse.Namespace) -> None:

     

       175
        
           with open(args.manpage_urls, 'r') as manpage_urls:

     

       176
       -
               md = DocBookSectionConverter(json.load(manpage_urls))

     

       177
       -
               for section in args.contents:

     

       178
       -
                   md.add_section(section.id, section.chapters)

     

       179
       -
               with open(args.outfile, 'w') as f:

     

       180
       -
                   f.write(md.finalize())

     

       181
       -
       

     

       182
       -
       def _run_cli_db_fragment(args: argparse.Namespace) -> None:

     

       183
       -
           with open(args.manpage_urls, 'r') as manpage_urls:

     

       184
       -
               md = DocBookFragmentConverter(json.load(manpage_urls))

     

       185
       -
               for kind in [ 'chapter', 'section' ]:

     

       186
       -
                   for (target, file) in getattr(args, kind):

     

       187
       -
                       converted = md.convert(file, kind)

     

       188
       -
                       target.parent.mkdir(parents=True, exist_ok=True)

     

       189
       -
                       target.write_text(converted)

     

       190
        
       

     

       191
        
       def build_cli(p: argparse.ArgumentParser) -> None:

     

       192
        
           formats = p.add_subparsers(dest='format', required=True)

     

       193
       -
           _build_cli_db_section(formats.add_parser('docbook-section'))

     

       194
       -
           _build_cli_db_fragment(formats.add_parser('docbook-fragment'))

     

       195
        
       

     

       196
        
       def run_cli(args: argparse.Namespace) -> None:

     

       197
       -
           if args.format == 'docbook-section':

     

       198
       -
               _run_cli_db_section(args)

     

       199
       -
           elif args.format == 'docbook-fragment':

     

       200
       -
               _run_cli_db_fragment(args)

     

       201
        
           else:

     

       202
        
               raise RuntimeError('format not hooked up', args)

···

       2
        
       import json

     

       3
        
       

     

       4
        
       from abc import abstractmethod

     

       5
       +
       from collections.abc import Mapping, MutableMapping, Sequence

     

       6
        
       from pathlib import Path

     

       7
        
       from typing import Any, cast, NamedTuple, Optional, Union

     

       8
        
       from xml.sax.saxutils import escape, quoteattr

     

       9
       +
       

     

       10
       +
       import markdown_it

     

       11
        
       from markdown_it.token import Token

     

       12
        
       from markdown_it.utils import OptionsDict

     

       13
        
       

     

       14
       +
       from . import options

     

       15
       +
       from .docbook import DocBookRenderer, Heading

     

       16
        
       from .md import Converter

     

       17
        
       

     

       18
       +
       class ManualDocBookRenderer(DocBookRenderer):

     

       19
       +
           _toplevel_tag: str

     

       0
        
       
     

       20
        
       

     

       21
       +
           def __init__(self, toplevel_tag: str, manpage_urls: Mapping[str, str],

     

       22
       +
                        parser: Optional[markdown_it.MarkdownIt] = None):

     

       23
       +
               super().__init__(manpage_urls, parser)

     

       24
       +
               self._toplevel_tag = toplevel_tag

     

       25
       +
               self.rules |= {

     

       26
       +
                   'included_sections': lambda *args: self._included_thing("section", *args),

     

       27
       +
                   'included_chapters': lambda *args: self._included_thing("chapter", *args),

     

       28
       +
                   'included_preface': lambda *args: self._included_thing("preface", *args),

     

       29
       +
                   'included_parts': lambda *args: self._included_thing("part", *args),

     

       30
       +
                   'included_appendix': lambda *args: self._included_thing("appendix", *args),

     

       31
       +
                   'included_options': self.included_options,

     

       32
       +
               }

     

       33
        
       

     

       34
       +
           def render(self, tokens: Sequence[Token], options: OptionsDict,

     

       35
       +
                      env: MutableMapping[str, Any]) -> str:

     

       36
       +
               wanted = { 'h1': 'title' }

     

       37
       +
               wanted |= { 'h2': 'subtitle' } if self._toplevel_tag == 'book' else {}

     

       38
       +
               for (i, (tag, kind)) in enumerate(wanted.items()):

     

       39
       +
                   if len(tokens) < 3 * (i + 1):

     

       40
       +
                       raise RuntimeError(f"missing {kind} ({tag}) heading")

     

       41
       +
                   token = tokens[3 * i]

     

       42
       +
                   if token.type != 'heading_open' or token.tag != tag:

     

       43
       +
                       assert token.map

     

       44
       +
                       raise RuntimeError(f"expected {kind} ({tag}) heading in line {token.map[0] + 1}", token)

     

       45
       +
               for t in tokens[3 * len(wanted):]:

     

       46
       +
                   if t.type != 'heading_open' or (info := wanted.get(t.tag)) is None:

     

       47
       +
                       continue

     

       48
       +
                   assert t.map

     

       49
       +
                   raise RuntimeError(

     

       50
       +
                       f"only one {info[0]} heading ({t.markup} [text...]) allowed per "

     

       51
       +
                       f"{self._toplevel_tag}, but found a second in lines [{t.map[0] + 1}..{t.map[1]}]. "

     

       52
       +
                       "please remove all such headings except the first or demote the subsequent headings.",

     

       53
       +
                       t)

     

       54
        
       

     

       55
       +
               # books get special handling because they have *two* title tags. doing this with

     

       56
       +
               # generic code is more complicated than it's worth. the checks above have verified

     

       57
       +
               # that both titles actually exist.

     

       58
       +
               if self._toplevel_tag == 'book':

     

       59
       +
                   assert tokens[1].children

     

       60
       +
                   assert tokens[4].children

     

       61
       +
                   if (maybe_id := cast(str, tokens[0].attrs.get('id', ""))):

     

       62
       +
                       maybe_id = "xml:id=" + quoteattr(maybe_id)

     

       63
       +
                   return (f'<book xmlns="http://docbook.org/ns/docbook"'

     

       64
       +
                           f'      xmlns:xlink="http://www.w3.org/1999/xlink"'

     

       65
       +
                           f'      {maybe_id} version="5.0">'

     

       66
       +
                           f'  <title>{self.renderInline(tokens[1].children, options, env)}</title>'

     

       67
       +
                           f'  <subtitle>{self.renderInline(tokens[4].children, options, env)}</subtitle>'

     

       68
       +
                           f'  {super().render(tokens[6:], options, env)}'

     

       69
       +
                           f'</book>')

     

       0
        
       
     

       70
        
       

     

       71
       +
               return super().render(tokens, options, env)

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       72
        
       

     

       73
        
           def _heading_tag(self, token: Token, tokens: Sequence[Token], i: int, options: OptionsDict,

     

       74
        
                            env: MutableMapping[str, Any]) -> tuple[str, dict[str, str]]:

     

       75
        
               (tag, attrs) = super()._heading_tag(token, tokens, i, options, env)

     

       76
       +
               # render() has already verified that we don't have supernumerary headings and since the

     

       77
       +
               # book tag is handled specially we can leave the check this simple

     

       78
       +
               if token.tag != 'h1':

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       79
        
                   return (tag, attrs)

     

       80
       +
               return (self._toplevel_tag, attrs | {

     

       0
        
       
     

       81
        
                   'xmlns': "http://docbook.org/ns/docbook",

     

       82
        
                   'xmlns:xlink': "http://www.w3.org/1999/xlink",

     

       83
        
               })

     

       84
        
       

     

       85
       +
           def _included_thing(self, tag: str, token: Token, tokens: Sequence[Token], i: int,

     

       86
       +
                               options: OptionsDict, env: MutableMapping[str, Any]) -> str:

     

       87
       +
               result = []

     

       88
       +
               # close existing partintro. the generic render doesn't really need this because

     

       89
       +
               # it doesn't have a concept of structure in the way the manual does.

     

       90
       +
               if self._headings and self._headings[-1] == Heading('part', 1):

     

       91
       +
                   result.append("</partintro>")

     

       92
       +
                   self._headings[-1] = self._headings[-1]._replace(partintro_closed=True)

     

       93
       +
               # must nest properly for structural includes. this requires saving at least

     

       94
       +
               # the headings stack, but creating new renderers is cheap and much easier.

     

       95
       +
               r = ManualDocBookRenderer(tag, self._manpage_urls, None)

     

       96
       +
               for (included, path) in token.meta['included']:

     

       97
       +
                   try:

     

       98
       +
                       result.append(r.render(included, options, env))

     

       99
       +
                   except Exception as e:

     

       100
       +
                       raise RuntimeError(f"rendering {path}") from e

     

       101
       +
               return "".join(result)

     

       102
       +
           def included_options(self, token: Token, tokens: Sequence[Token], i: int, options: OptionsDict,

     

       103
       +
                                env: MutableMapping[str, Any]) -> str:

     

       104
       +
               return cast(str, token.meta['rendered-options'])

     

       105
       +
       

     

       106
        
           # TODO minimize docbook diffs with existing conversions. remove soon.

     

       107
        
           def paragraph_open(self, token: Token, tokens: Sequence[Token], i: int, options: OptionsDict,

     

       108
        
                              env: MutableMapping[str, Any]) -> str:

     
···

       115
        
               return f"<programlisting>\n{escape(token.content)}</programlisting>"

     

       116
        
           def fence(self, token: Token, tokens: Sequence[Token], i: int, options: OptionsDict,

     

       117
        
                     env: MutableMapping[str, Any]) -> str:

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       118
        
               info = f" language={quoteattr(token.info)}" if token.info != "" else ""

     

       119
        
               return f"<programlisting{info}>\n{escape(token.content)}</programlisting>"

     

       120
        
       

     

       121
       +
       class DocBookConverter(Converter):

     

       122
       +
           def __renderer__(self, manpage_urls: Mapping[str, str],

     

       123
       +
                            parser: Optional[markdown_it.MarkdownIt]) -> ManualDocBookRenderer:

     

       124
       +
               return ManualDocBookRenderer('book', manpage_urls, parser)

     

       125
        
       

     

       126
       +
           _base_paths: list[Path]

     

       127
       +
           _revision: str

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       128
        
       

     

       129
       +
           def __init__(self, manpage_urls: Mapping[str, str], revision: str):

     

       130
       +
               super().__init__(manpage_urls)

     

       131
       +
               self._revision = revision

     

       132
        
       

     

       133
       +
           def convert(self, file: Path) -> str:

     

       134
       +
               self._base_paths = [ file ]

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       135
        
               try:

     

       136
        
                   with open(file, 'r') as f:

     

       0
        
       
     

       0
        
       
     

       137
        
                       return self._render(f.read())

     

       138
        
               except Exception as e:

     

       139
       +
                   raise RuntimeError(f"failed to render manual {file}") from e

     

       140
        
       

     

       141
       +
           def _parse(self, src: str, env: Optional[MutableMapping[str, Any]] = None) -> list[Token]:

     

       142
       +
               tokens = super()._parse(src, env)

     

       143
       +
               for token in tokens:

     

       144
       +
                   if token.type != "fence" or not token.info.startswith("{=include=} "):

     

       145
       +
                       continue

     

       146
       +
                   typ = token.info[12:].strip()

     

       147
       +
                   if typ == 'options':

     

       148
       +
                       token.type = 'included_options'

     

       149
       +
                       self._parse_options(token)

     

       150
       +
                   elif typ in [ 'sections', 'chapters', 'preface', 'parts', 'appendix' ]:

     

       151
       +
                       token.type = 'included_' + typ

     

       152
       +
                       self._parse_included_blocks(token, env)

     

       153
       +
                   else:

     

       154
       +
                       raise RuntimeError(f"unsupported structural include type '{typ}'")

     

       155
       +
               return tokens

     

       156
        
       

     

       157
       +
           def _parse_included_blocks(self, token: Token, env: Optional[MutableMapping[str, Any]]) -> None:

     

       158
       +
               assert token.map

     

       159
       +
               included = token.meta['included'] = []

     

       160
       +
               for (lnum, line) in enumerate(token.content.splitlines(), token.map[0] + 2):

     

       161
       +
                   line = line.strip()

     

       162
       +
                   path = self._base_paths[-1].parent / line

     

       163
       +
                   if path in self._base_paths:

     

       164
       +
                       raise RuntimeError(f"circular include found in line {lnum}")

     

       165
       +
                   try:

     

       166
       +
                       self._base_paths.append(path)

     

       167
       +
                       with open(path, 'r') as f:

     

       168
       +
                           tokens = self._parse(f.read(), env)

     

       169
       +
                           included.append((tokens, path))

     

       170
       +
                       self._base_paths.pop()

     

       171
       +
                   except Exception as e:

     

       172
       +
                       raise RuntimeError(f"processing included file {path} from line {lnum}") from e

     

       173
        
       

     

       174
       +
           def _parse_options(self, token: Token) -> None:

     

       175
       +
               assert token.map

     

       0
        
       
     

       176
        
       

     

       177
       +
               items = {}

     

       178
       +
               for (lnum, line) in enumerate(token.content.splitlines(), token.map[0] + 2):

     

       179
       +
                   if len(args := line.split(":", 1)) != 2:

     

       180
       +
                       raise RuntimeError(f"options directive with no argument in line {lnum}")

     

       181
       +
                   (k, v) = (args[0].strip(), args[1].strip())

     

       182
       +
                   if k in items:

     

       183
       +
                       raise RuntimeError(f"duplicate options directive {k} in line {lnum}")

     

       184
       +
                   items[k] = v

     

       185
       +
               try:

     

       186
       +
                   id_prefix = items.pop('id-prefix')

     

       187
       +
                   varlist_id = items.pop('list-id')

     

       188
       +
                   source = items.pop('source')

     

       189
       +
               except KeyError as e:

     

       190
       +
                   raise RuntimeError(f"options directive {e} missing in block at line {token.map[0] + 1}")

     

       191
       +
               if items.keys():

     

       192
       +
                   raise RuntimeError(

     

       193
       +
                       f"unsupported options directives in block at line {token.map[0] + 1}",

     

       194
       +
                       " ".join(items.keys()))

     

       195
        
       

     

       196
       +
               try:

     

       197
       +
                   conv = options.DocBookConverter(

     

       198
       +
                       self._manpage_urls, self._revision, False, 'fragment', varlist_id, id_prefix)

     

       199
       +
                   with open(self._base_paths[-1].parent / source, 'r') as f:

     

       200
       +
                       conv.add_options(json.load(f))

     

       201
       +
                   token.meta['rendered-options'] = conv.finalize(fragment=True)

     

       202
       +
               except Exception as e:

     

       203
       +
                   raise RuntimeError(f"processing options block in line {token.map[0] + 1}") from e

     

       204
        
       

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       205
        
       

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       206
        
       

     

       207
       +
       def _build_cli_db(p: argparse.ArgumentParser) -> None:

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       208
        
           p.add_argument('--manpage-urls', required=True)

     

       209
       +
           p.add_argument('--revision', required=True)

     

       210
       +
           p.add_argument('infile', type=Path)

     

       211
       +
           p.add_argument('outfile', type=Path)

     

       212
        
       

     

       213
       +
       def _run_cli_db(args: argparse.Namespace) -> None:

     

       214
        
           with open(args.manpage_urls, 'r') as manpage_urls:

     

       215
       +
               md = DocBookConverter(json.load(manpage_urls), args.revision)

     

       216
       +
               converted = md.convert(args.infile)

     

       217
       +
               args.outfile.write_text(converted)

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       218
        
       

     

       219
        
       def build_cli(p: argparse.ArgumentParser) -> None:

     

       220
        
           formats = p.add_subparsers(dest='format', required=True)

     

       221
       +
           _build_cli_db(formats.add_parser('docbook'))

     

       0
        
       
     

       222
        
       

     

       223
        
       def run_cli(args: argparse.Namespace) -> None:

     

       224
       +
           if args.format == 'docbook':

     

       225
       +
               _run_cli_db(args)

     

       0
        
       
     

       0
        
       
     

       226
        
           else:

     

       227
        
               raise RuntimeError('format not hooked up', args)

+3 -2

pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/options.py

···

       231
        
           def _decl_def_footer(self) -> list[str]:

     

       232
        
               return [ "</simplelist>" ]

     

       233
        
       

     

       234
       -
           def finalize(self) -> str:

     

       235
        
               result = []

     

       236
        
       

     

       237
       -
               result.append('<?xml version="1.0" encoding="UTF-8"?>')

     

       0
        
       
     

       238
        
               if self._document_type == 'appendix':

     

       239
        
                   result += [

     

       240
        
                       '<appendix xmlns="http://docbook.org/ns/docbook"',

···

       231
        
           def _decl_def_footer(self) -> list[str]:

     

       232
        
               return [ "</simplelist>" ]

     

       233
        
       

     

       234
       +
           def finalize(self, *, fragment: bool = False) -> str:

     

       235
        
               result = []

     

       236
        
       

     

       237
       +
               if not fragment:

     

       238
       +
                   result.append('<?xml version="1.0" encoding="UTF-8"?>')

     

       239
        
               if self._document_type == 'appendix':

     

       240
        
                   result += [

     

       241
        
                       '<appendix xmlns="http://docbook.org/ns/docbook"',