Merge pull request #39649 from grahamc/hacking-docs

NixOS docs: making it easier to hack on

nixos/doc/manual/Makefile

@@ -0,0 +1,8 @@
+debug:
+	nix-shell --packages xmloscopy \
+		--run 'xmloscopy --docbook5 ./manual.xml ./manual-combined.xml'
+
+generated: ./options-to-docbook.xsl
+	nix-build ../../release.nix \
+		--attr manualGeneratedSources.x86_64-linux \
+		--out-link ./generated

nixos/doc/manual/configuration/configuration.xml

@@ -25,9 +25,8 @@ effect after you run <command>nixos-rebuild</command>.</para>
 <xi:include href="networking.xml" />
 <xi:include href="linux-kernel.xml" />
 
-<xi:include href="modules.xml" xpointer="xpointer(//section[@id='modules']/*)" />
+<xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" />
 
 <!-- Apache; libvirtd virtualisation -->
 
 </part>
-

nixos/doc/manual/default.nix

@@ -102,13 +102,18 @@ let
     </section>
   '';
 
+  generatedSources = runCommand "generated-docbook" {} ''
+    mkdir $out
+    ln -s ${modulesDoc} $out/modules.xml
+    ln -s ${optionsDocBook} $out/options-db.xml
+    printf "%s" "${version}" > $out/version
+  '';
+
   copySources =
     ''
       cp -prd $sources/* . # */
+      ln -s ${generatedSources} ./generated
       chmod -R u+w .
-      ln -s ${modulesDoc} configuration/modules.xml
-      ln -s ${optionsDocBook} options-db.xml
-      printf "%s" "${version}" > version
     '';
 
   toc = builtins.toFile "toc.xml"
@@ -224,6 +229,7 @@ let
     '';
 
 in rec {
+  inherit generatedSources;
 
   # The NixOS options in JSON format.
   optionsJSON = runCommand "options-json"

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

@@ -18,13 +18,25 @@
 <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. If you make modifications to
-  the manual, it's important to build it before committing. You can do
-  that as follows:
-
-  <screen>nix-build nixos/release.nix -A manual.x86_64-linux</screen>
+  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

nixos/doc/manual/man-configuration.xml

@@ -31,7 +31,8 @@ therein.</para>
 <para>You can use the following options in
 <filename>configuration.nix</filename>.</para>
 
-<xi:include href="options-db.xml" />
+<xi:include href="./generated/options-db.xml"
+            xpointer="configuration-variable-list" />
 
 </refsection>
 

nixos/doc/manual/manual.xml

@@ -6,7 +6,7 @@
 
   <info>
     <title>NixOS Manual</title>
-    <subtitle>Version <xi:include href="version" parse="text" /></subtitle>
+    <subtitle>Version <xi:include href="./generated/version" parse="text" /></subtitle>
   </info>
 
   <preface>
@@ -39,7 +39,8 @@
 
   <appendix xml:id="ch-options">
     <title>Configuration Options</title>
-    <xi:include href="options-db.xml" />
+    <xi:include href="./generated/options-db.xml"
+                xpointer="configuration-variable-list" />
   </appendix>
 
   <xi:include href="release-notes/release-notes.xml" />

nixos/doc/manual/options-to-docbook.xsl

@@ -15,9 +15,9 @@
 
 
   <xsl:template match="/expr/list">
-
-      <variablelist>
-
+    <appendix>
+      <title>Configuration Options</title>
+      <variablelist xml:id="configuration-variable-list">
         <xsl:for-each select="attrs">
           <xsl:variable name="id" select="concat('opt-', str:replace(str:replace(str:replace(str:replace(attr[@name = 'name']/string/@value, '*', '_'), '&lt;', '_'), '>', '_'), '?', '_'))" />
           <varlistentry>
@@ -100,7 +100,7 @@
         </xsl:for-each>
 
       </variablelist>
-
+    </appendix>
   </xsl:template>
 
 

nixos/release.nix

@@ -124,7 +124,6 @@ let
         preferLocalBuild = true;
       };
 
-
 in rec {
 
   channel = import lib/make-channel.nix { inherit pkgs nixpkgs version versionSuffix; };
@@ -132,6 +131,7 @@ in rec {
   manual = buildFromConfig ({ pkgs, ... }: { }) (config: config.system.build.manual.manual);
   manualEpub = (buildFromConfig ({ pkgs, ... }: { }) (config: config.system.build.manual.manualEpub));
   manpages = buildFromConfig ({ pkgs, ... }: { }) (config: config.system.build.manual.manpages);
+  manualGeneratedSources = buildFromConfig ({ pkgs, ... }: { }) (config: config.system.build.manual.generatedSources);
   options = (buildFromConfig ({ pkgs, ... }: { }) (config: config.system.build.manual.optionsJSON)).x86_64-linux;