pennae 1229e735ac 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.

2023-02-12 13:02:42 +01:00

3.6 KiB

Raw Blame History

Writing NixOS Documentation

As NixOS grows, so too does the need for a catalogue and explanation of its extensive functionality. Collecting pertinent information from disparate sources and presenting it in an accessible style would be a worthy contribution to the project.

Building the Manual

The DocBook sources of the are in the nixos/doc/manual subdirectory of the Nixpkgs repository.

You can quickly validate your edits with make:

$ cd /path/to/nixpkgs/nixos/doc/manual
$ nix-shell
nix-shell$ make

Once you are done making modifications to the manual, it's important to build it before committing. You can do that as follows:

nix-build nixos/release.nix -A manual.x86_64-linux

When this command successfully finishes, it will tell you where the manual got generated. The HTML will be accessible through the result symlink at ./result/share/doc/nixos/index.html.

Editing DocBook XML

For general information on how to write in DocBook, see DocBook 5: The Definitive Guide.

Emacs nXML Mode is very helpful for editing DocBook XML because it validates the document as you write, and precisely locates errors. To use it, see .

Pandoc can generate DocBook XML from a multitude of formats, which makes a good starting point. Here is an example of Pandoc invocation to convert GitHub-Flavoured MarkDown to DocBook 5 XML:

pandoc -f markdown_github -t docbook5 docs.md -o my-section.md

Pandoc can also quickly convert a single section.xml to HTML, which is helpful when drafting.

Sometimes writing valid DocBook is simply too difficult. In this case, submit your documentation updates in a GitHub Issue and someone will handle the conversion to XML for you.

Creating a Topic

You can use an existing topic as a basis for the new topic or create a topic from scratch.

Keep the following guidelines in mind when you create and add a topic:

The NixOS book element is in nixos/doc/manual/manual.xml. It includes several parts which are in subdirectories.
Store the topic file in the same directory as the part to which it belongs. If your topic is about configuring a NixOS module, then the XML file can be stored alongside the module definition nix file.
If you include multiple words in the file name, separate the words with a dash. For example: ipv6-config.xml.
Make sure that the xml:id value is unique. You can use abbreviations if the ID is too long. For example: nixos-config.
Determine whether your topic is a chapter or a section. If you are unsure, open an existing topic file and check whether the main element is chapter or section.

Adding a Topic to the Book

Open the parent CommonMark file and add a line to the list of chapters with the file name of the topic that you created. If you created a section, you add the file to the chapter file. If you created a chapter, you add the file to the part file.

If the topic is about configuring a NixOS module, it can be automatically included in the manual by using the meta.doc attribute. See for an explanation.

3.6 KiB Raw Blame History