diff options
author | pennae <github@quasiparticle.net> | 2023-02-11 08:48:06 +0100 |
---|---|---|
committer | pennae <github@quasiparticle.net> | 2023-02-12 13:02:42 +0100 |
commit | 1229e735ac51dbe79724f7648655a2089c9c67b9 (patch) | |
tree | ba4f6a33e11574bde4108f67928b3f24ccfee901 /nixos/doc/manual/configuration | |
parent | 8b7f0e559ad9419815d0a4c8d231e2bf464c0ad2 (diff) |
nixos-render-docs: add structural includes, use for manual
this adds support for structural includes to nixos-render-docs. structural includes provide a way to denote the (sub)structure of the nixos manual in the markdown source files, very similar to how we used literal docbook blocks before, and are processed by nixos-render-docs without involvement of xml tooling. this will ultimately allow us to emit the nixos manual in other formats as well, e.g. html, without going through docbook at all. alternatives to this source layout were also considered: a parallel structure using e.g. toml files that describe the document tree and links to each part is possible, but much more complicated to implement than the solution chosen here and makes it harder to follow which files have what substructure. it also makes it much harder to include a substructure in the middle of a file. much the same goes for command-line arguments to the converter, only that command-lined arguments are even harder to specify correctly and cannot be reasonably pulled together from many places without involving another layer of tooling. cli arguments would also mean that the manual structure would be fixed in default.nix, which is also not ideal.
Diffstat (limited to 'nixos/doc/manual/configuration')
8 files changed, 61 insertions, 65 deletions
diff --git a/nixos/doc/manual/configuration/config-syntax.chapter.md b/nixos/doc/manual/configuration/config-syntax.chapter.md index 9f8d45d588997..9e606b2b82af3 100644 --- a/nixos/doc/manual/configuration/config-syntax.chapter.md +++ b/nixos/doc/manual/configuration/config-syntax.chapter.md @@ -11,8 +11,8 @@ manual](https://nixos.org/nix/manual/#chap-writing-nix-expressions), but here we give a short overview of the most important constructs useful in NixOS configuration files. -```{=docbook} -<xi:include href="config-file.section.xml" /> -<xi:include href="abstractions.section.xml" /> -<xi:include href="modularity.section.xml" /> +```{=include=} sections +config-file.section.md +abstractions.section.md +modularity.section.md ``` diff --git a/nixos/doc/manual/configuration/configuration.md b/nixos/doc/manual/configuration/configuration.md new file mode 100644 index 0000000000000..4c966f3325b99 --- /dev/null +++ b/nixos/doc/manual/configuration/configuration.md @@ -0,0 +1,27 @@ +# Configuration {#ch-configuration} + +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`. + +```{=include=} chapters +config-syntax.chapter.md +package-mgmt.chapter.md +user-mgmt.chapter.md +file-systems.chapter.md +x-windows.chapter.md +wayland.chapter.md +gpu-accel.chapter.md +xfce.chapter.md +networking.chapter.md +linux-kernel.chapter.md +subversion.chapter.md +``` + +```{=include=} chapters +@MODULE_CHAPTERS@ +``` + +```{=include=} chapters +profiles.chapter.md +kubernetes.chapter.md +``` +<!-- Apache; libvirtd virtualisation --> diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml deleted file mode 100644 index b04316cfa48e2..0000000000000 --- a/nixos/doc/manual/configuration/configuration.xml +++ /dev/null @@ -1,31 +0,0 @@ -<part xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ch-configuration"> - <title>Configuration</title> - <partintro xml:id="ch-configuration-intro"> - <para> - This chapter describes how to configure various aspects of a NixOS machine - through the configuration file - <filename>/etc/nixos/configuration.nix</filename>. As described in - <xref linkend="sec-changing-config" />, changes to this file only take - effect after you run <command>nixos-rebuild</command>. - </para> - </partintro> - <xi:include href="../from_md/configuration/config-syntax.chapter.xml" /> - <xi:include href="../from_md/configuration/package-mgmt.chapter.xml" /> - <xi:include href="../from_md/configuration/user-mgmt.chapter.xml" /> - <xi:include href="../from_md/configuration/file-systems.chapter.xml" /> - <xi:include href="../from_md/configuration/x-windows.chapter.xml" /> - <xi:include href="../from_md/configuration/wayland.chapter.xml" /> - <xi:include href="../from_md/configuration/gpu-accel.chapter.xml" /> - <xi:include href="../from_md/configuration/xfce.chapter.xml" /> - <xi:include href="../from_md/configuration/networking.chapter.xml" /> - <xi:include href="../from_md/configuration/linux-kernel.chapter.xml" /> - <xi:include href="../from_md/configuration/subversion.chapter.xml" /> - <xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" /> - <xi:include href="../from_md/configuration/profiles.chapter.xml" /> - <xi:include href="../from_md/configuration/kubernetes.chapter.xml" /> -<!-- Apache; libvirtd virtualisation --> -</part> diff --git a/nixos/doc/manual/configuration/declarative-packages.section.md b/nixos/doc/manual/configuration/declarative-packages.section.md index 337cdf8472e40..02eaa56192e46 100644 --- a/nixos/doc/manual/configuration/declarative-packages.section.md +++ b/nixos/doc/manual/configuration/declarative-packages.section.md @@ -40,7 +40,7 @@ configuration use `pkgs` prefix (variable). To "uninstall" a package, simply remove it from [](#opt-environment.systemPackages) and run `nixos-rebuild switch`. -```{=docbook} -<xi:include href="customizing-packages.section.xml" /> -<xi:include href="adding-custom-packages.section.xml" /> +```{=include=} sections +customizing-packages.section.md +adding-custom-packages.section.md ``` diff --git a/nixos/doc/manual/configuration/file-systems.chapter.md b/nixos/doc/manual/configuration/file-systems.chapter.md index 901e2e4f181b3..aca978be064d3 100644 --- a/nixos/doc/manual/configuration/file-systems.chapter.md +++ b/nixos/doc/manual/configuration/file-systems.chapter.md @@ -36,7 +36,7 @@ dropping you to the emergency shell. You can make a mount asynchronous and non-critical by adding `options = [ "nofail" ];`. ::: -```{=docbook} -<xi:include href="luks-file-systems.section.xml" /> -<xi:include href="sshfs-file-systems.section.xml" /> +```{=include=} sections +luks-file-systems.section.md +sshfs-file-systems.section.md ``` diff --git a/nixos/doc/manual/configuration/networking.chapter.md b/nixos/doc/manual/configuration/networking.chapter.md index 529dc0610bdaf..abbd9766f173b 100644 --- a/nixos/doc/manual/configuration/networking.chapter.md +++ b/nixos/doc/manual/configuration/networking.chapter.md @@ -3,14 +3,14 @@ This section describes how to configure networking components on your NixOS machine. -```{=docbook} -<xi:include href="network-manager.section.xml" /> -<xi:include href="ssh.section.xml" /> -<xi:include href="ipv4-config.section.xml" /> -<xi:include href="ipv6-config.section.xml" /> -<xi:include href="firewall.section.xml" /> -<xi:include href="wireless.section.xml" /> -<xi:include href="ad-hoc-network-config.section.xml" /> -<xi:include href="renaming-interfaces.section.xml" /> +```{=include=} sections +network-manager.section.md +ssh.section.md +ipv4-config.section.md +ipv6-config.section.md +firewall.section.md +wireless.section.md +ad-hoc-network-config.section.md +renaming-interfaces.section.md ``` <!-- TODO: OpenVPN, NAT --> diff --git a/nixos/doc/manual/configuration/package-mgmt.chapter.md b/nixos/doc/manual/configuration/package-mgmt.chapter.md index a6c414be59a97..1148bbe84740c 100644 --- a/nixos/doc/manual/configuration/package-mgmt.chapter.md +++ b/nixos/doc/manual/configuration/package-mgmt.chapter.md @@ -12,7 +12,7 @@ NixOS has two distinct styles of package management: `nix-env` command. This style allows mixing packages from different Nixpkgs versions. It's the only choice for non-root users. -```{=docbook} -<xi:include href="declarative-packages.section.xml" /> -<xi:include href="ad-hoc-packages.section.xml" /> +```{=include=} sections +declarative-packages.section.md +ad-hoc-packages.section.md ``` diff --git a/nixos/doc/manual/configuration/profiles.chapter.md b/nixos/doc/manual/configuration/profiles.chapter.md index 2c3dea27c1818..9f1f48f742ac5 100644 --- a/nixos/doc/manual/configuration/profiles.chapter.md +++ b/nixos/doc/manual/configuration/profiles.chapter.md @@ -19,16 +19,16 @@ install media, many are actually intended to be used in real installs. What follows is a brief explanation on the purpose and use-case for each profile. Detailing each option configured by each one is out of scope. -```{=docbook} -<xi:include href="profiles/all-hardware.section.xml" /> -<xi:include href="profiles/base.section.xml" /> -<xi:include href="profiles/clone-config.section.xml" /> -<xi:include href="profiles/demo.section.xml" /> -<xi:include href="profiles/docker-container.section.xml" /> -<xi:include href="profiles/graphical.section.xml" /> -<xi:include href="profiles/hardened.section.xml" /> -<xi:include href="profiles/headless.section.xml" /> -<xi:include href="profiles/installation-device.section.xml" /> -<xi:include href="profiles/minimal.section.xml" /> -<xi:include href="profiles/qemu-guest.section.xml" /> +```{=include=} sections +profiles/all-hardware.section.md +profiles/base.section.md +profiles/clone-config.section.md +profiles/demo.section.md +profiles/docker-container.section.md +profiles/graphical.section.md +profiles/hardened.section.md +profiles/headless.section.md +profiles/installation-device.section.md +profiles/minimal.section.md +profiles/qemu-guest.section.md ``` |