pyrox.dev
1<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="sec-writing-documentation">
2 <title>Writing NixOS Documentation</title>
3 <para>
4 As NixOS grows, so too does the need for a catalogue and explanation
5 of its extensive functionality. Collecting pertinent information
6 from disparate sources and presenting it in an accessible style
7 would be a worthy contribution to the project.
8 </para>
9 <section xml:id="sec-writing-docs-building-the-manual">
10 <title>Building the Manual</title>
11 <para>
12 The DocBook sources of the <xref linkend="book-nixos-manual" />
13 are in the
14 <link xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual"><literal>nixos/doc/manual</literal></link>
15 subdirectory of the Nixpkgs repository.
16 </para>
17 <para>
18 You can quickly validate your edits with <literal>make</literal>:
19 </para>
20 <programlisting>
21$ cd /path/to/nixpkgs/nixos/doc/manual
22$ nix-shell
23nix-shell$ make
24</programlisting>
25 <para>
26 Once you are done making modifications to the manual, it's
27 important to build it before committing. You can do that as
28 follows:
29 </para>
30 <programlisting>
31nix-build nixos/release.nix -A manual.x86_64-linux
32</programlisting>
33 <para>
34 When this command successfully finishes, it will tell you where
35 the manual got generated. The HTML will be accessible through the
36 <literal>result</literal> symlink at
37 <literal>./result/share/doc/nixos/index.html</literal>.
38 </para>
39 </section>
40 <section xml:id="sec-writing-docs-editing-docbook-xml">
41 <title>Editing DocBook XML</title>
42 <para>
43 For general information on how to write in DocBook, see
44 <link xlink:href="http://www.docbook.org/tdg5/en/html/docbook.html">DocBook
45 5: The Definitive Guide</link>.
46 </para>
47 <para>
48 Emacs nXML Mode is very helpful for editing DocBook XML because it
49 validates the document as you write, and precisely locates errors.
50 To use it, see <xref linkend="sec-emacs-docbook-xml" />.
51 </para>
52 <para>
53 <link xlink:href="http://pandoc.org">Pandoc</link> can generate
54 DocBook XML from a multitude of formats, which makes a good
55 starting point. Here is an example of Pandoc invocation to convert
56 GitHub-Flavoured MarkDown to DocBook 5 XML:
57 </para>
58 <programlisting>
59pandoc -f markdown_github -t docbook5 docs.md -o my-section.md
60</programlisting>
61 <para>
62 Pandoc can also quickly convert a single
63 <literal>section.xml</literal> to HTML, which is helpful when
64 drafting.
65 </para>
66 <para>
67 Sometimes writing valid DocBook is simply too difficult. In this
68 case, submit your documentation updates in a
69 <link xlink:href="https://github.com/NixOS/nixpkgs/issues/new">GitHub
70 Issue</link> and someone will handle the conversion to XML for
71 you.
72 </para>
73 </section>
74 <section xml:id="sec-writing-docs-creating-a-topic">
75 <title>Creating a Topic</title>
76 <para>
77 You can use an existing topic as a basis for the new topic or
78 create a topic from scratch.
79 </para>
80 <para>
81 Keep the following guidelines in mind when you create and add a
82 topic:
83 </para>
84 <itemizedlist>
85 <listitem>
86 <para>
87 The NixOS
88 <link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><literal>book</literal></link>
89 element is in <literal>nixos/doc/manual/manual.xml</literal>.
90 It includes several
91 <link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><literal>parts</literal></link>
92 which are in subdirectories.
93 </para>
94 </listitem>
95 <listitem>
96 <para>
97 Store the topic file in the same directory as the
98 <literal>part</literal> to which it belongs. If your topic is
99 about configuring a NixOS module, then the XML file can be
100 stored alongside the module definition <literal>nix</literal>
101 file.
102 </para>
103 </listitem>
104 <listitem>
105 <para>
106 If you include multiple words in the file name, separate the
107 words with a dash. For example:
108 <literal>ipv6-config.xml</literal>.
109 </para>
110 </listitem>
111 <listitem>
112 <para>
113 Make sure that the <literal>xml:id</literal> value is unique.
114 You can use abbreviations if the ID is too long. For example:
115 <literal>nixos-config</literal>.
116 </para>
117 </listitem>
118 <listitem>
119 <para>
120 Determine whether your topic is a chapter or a section. If you
121 are unsure, open an existing topic file and check whether the
122 main element is chapter or section.
123 </para>
124 </listitem>
125 </itemizedlist>
126 </section>
127 <section xml:id="sec-writing-docs-adding-a-topic">
128 <title>Adding a Topic to the Book</title>
129 <para>
130 Open the parent XML file and add an <literal>xi:include</literal>
131 element to the list of chapters with the file name of the topic
132 that you created. If you created a <literal>section</literal>, you
133 add the file to the <literal>chapter</literal> file. If you
134 created a <literal>chapter</literal>, you add the file to the
135 <literal>part</literal> file.
136 </para>
137 <para>
138 If the topic is about configuring a NixOS module, it can be
139 automatically included in the manual by using the
140 <literal>meta.doc</literal> attribute. See
141 <xref linkend="sec-meta-attributes" /> for an explanation.
142 </para>
143 </section>
144</chapter>