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