nixpkgs/nixos/doc/manual/development/writing-documentation.xml

<chapter 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="sec-writing-documentation">
 <title>Writing NixOS Documentation</title>
 <para>
  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.
 </para>
 <section>
  <title>Building the Manual</title>

  <para>
   The DocBook sources of the <xref linkend="book-nixos-manual"/> are in the
   <link xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual"><filename>nixos/doc/manual</filename></link>
   subdirectory of the Nixpkgs repository.
  </para>

  <para>
   You can quickly validate your edits with <command>make</command>:
  </para>

<screen>
  $ cd /path/to/nixpkgs/nixos/doc/manual
  $ make
</screen>

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

<screen>nix-build nixos/release.nix -A manual.x86_64-linux</screen>

  <para>
   When this command successfully finishes, it will tell you where the manual
   got generated. The HTML will be accessible through the
   <filename>result</filename> symlink at
   <filename>./result/share/doc/nixos/index.html</filename>.
  </para>
 </section>
 <section>
  <title>Editing DocBook XML</title>

  <para>
   For general information on how to write in DocBook, see
   <link xlink:href="http://www.docbook.org/tdg5/en/html/docbook.html"> DocBook
   5: The Definitive Guide</link>.
  </para>

  <para>
   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
   <xref linkend="sec-emacs-docbook-xml"/>.
  </para>

  <para>
   <link xlink:href="http://pandoc.org">Pandoc</link> can generate DocBook XML
   from a multitude of formats, which makes a good starting point.
   <example xml:id="ex-pandoc-xml-conv">
    <title>Pandoc invocation to convert GitHub-Flavoured MarkDown to DocBook 5 XML</title>
<screen>pandoc -f markdown_github -t docbook5 docs.md -o my-section.md</screen>
   </example>
   Pandoc can also quickly convert a single <filename>section.xml</filename> to
   HTML, which is helpful when drafting.
  </para>

  <para>
   Sometimes writing valid DocBook is simply too difficult. In this case,
   submit your documentation updates in a
   <link
  xlink:href="https://github.com/NixOS/nixpkgs/issues/new">GitHub
   Issue</link> and someone will handle the conversion to XML for you.
  </para>
 </section>
 <section>
  <title>Creating a Topic</title>

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

  <para>
   Keep the following guidelines in mind when you create and add a topic:
   <itemizedlist>
    <listitem>
     <para>
      The NixOS
      <link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><tag>book</tag></link>
      element is in <filename>nixos/doc/manual/manual.xml</filename>. It
      includes several
      <link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><tag>part</tag>s</link>
      which are in subdirectories.
     </para>
    </listitem>
    <listitem>
     <para>
      Store the topic file in the same directory as the <tag>part</tag> to
      which it belongs. If your topic is about configuring a NixOS module, then
      the XML file can be stored alongside the module definition
      <filename>nix</filename> file.
     </para>
    </listitem>
    <listitem>
     <para>
      If you include multiple words in the file name, separate the words with a
      dash. For example: <filename>ipv6-config.xml</filename>.
     </para>
    </listitem>
    <listitem>
     <para>
      Make sure that the <tag>xml:id</tag> value is unique. You can use
      abbreviations if the ID is too long. For example:
      <varname>nixos-config</varname>.
     </para>
    </listitem>
    <listitem>
     <para>
      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.
     </para>
    </listitem>
   </itemizedlist>
  </para>
 </section>
 <section>
  <title>Adding a Topic to the Book</title>

  <para>
   Open the parent XML file and add an <varname>xi:include</varname> element to
   the list of chapters with the file name of the topic that you created. If
   you created a <tag>section</tag>, you add the file to the <tag>chapter</tag>
   file. If you created a <tag>chapter</tag>, you add the file to the
   <tag>part</tag> file.
  </para>

  <para>
   If the topic is about configuring a NixOS module, it can be automatically
   included in the manual by using the <varname>meta.doc</varname> attribute.
   See <xref
  linkend="sec-meta-attributes"/> for an explanation.
  </para>
 </section>
</chapter>