From 59f8b1e844d679d1ae7d2a94cf02f9ca259f0dfa Mon Sep 17 00:00:00 2001
From: Graham Christensen <graham@grahamc.com>
Date: Fri, 27 Apr 2018 22:44:25 -0400
Subject: [PATCH 1/4] nixos docs: Move generated XML in to a specific
subdirectory to allow easier hacking
---
nixos/doc/manual/configuration/configuration.xml | 3 +--
nixos/doc/manual/default.nix | 11 ++++++++---
nixos/doc/manual/man-configuration.xml | 2 +-
nixos/doc/manual/manual.xml | 4 ++--
4 files changed, 12 insertions(+), 8 deletions(-)
diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml
index 8677c13db40..f092c7e207f 100644
--- a/nixos/doc/manual/configuration/configuration.xml
+++ b/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>
-
diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix
index ac22712baf8..c396c799c63 100644
--- a/nixos/doc/manual/default.nix
+++ b/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"
diff --git a/nixos/doc/manual/man-configuration.xml b/nixos/doc/manual/man-configuration.xml
index 05531b3909a..89d321d6972 100644
--- a/nixos/doc/manual/man-configuration.xml
+++ b/nixos/doc/manual/man-configuration.xml
@@ -31,7 +31,7 @@ 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" />
</refsection>
diff --git a/nixos/doc/manual/manual.xml b/nixos/doc/manual/manual.xml
index 9aa332f026d..a7825579e03 100644
--- a/nixos/doc/manual/manual.xml
+++ b/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,7 @@
<appendix xml:id="ch-options">
<title>Configuration Options</title>
- <xi:include href="options-db.xml" />
+ <xi:include href="./generated/options-db.xml" />
</appendix>
<xi:include href="release-notes/release-notes.xml" />
From 0ff0d138e4e9d68853c463a540d61718aa91cffb Mon Sep 17 00:00:00 2001
From: Graham Christensen <graham@grahamc.com>
Date: Sat, 28 Apr 2018 04:00:55 -0400
Subject: [PATCH 2/4] nixos docs: Add a makefile for hacking on the nixos docs
---
nixos/doc/manual/Makefile | 8 ++++++++
nixos/doc/manual/default.nix | 1 +
nixos/doc/manual/manual.xml | 3 ++-
nixos/doc/manual/options-to-docbook.xsl | 8 ++++----
nixos/release.nix | 2 +-
5 files changed, 16 insertions(+), 6 deletions(-)
create mode 100644 nixos/doc/manual/Makefile
diff --git a/nixos/doc/manual/Makefile b/nixos/doc/manual/Makefile
new file mode 100644
index 00000000000..b15fbaa270f
--- /dev/null
+++ b/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
diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix
index c396c799c63..2c6309474b3 100644
--- a/nixos/doc/manual/default.nix
+++ b/nixos/doc/manual/default.nix
@@ -229,6 +229,7 @@ let
'';
in rec {
+ inherit generatedSources;
# The NixOS options in JSON format.
optionsJSON = runCommand "options-json"
diff --git a/nixos/doc/manual/manual.xml b/nixos/doc/manual/manual.xml
index a7825579e03..676924e5c8b 100644
--- a/nixos/doc/manual/manual.xml
+++ b/nixos/doc/manual/manual.xml
@@ -39,7 +39,8 @@
<appendix xml:id="ch-options">
<title>Configuration Options</title>
- <xi:include href="./generated/options-db.xml" />
+ <xi:include href="./generated/options-db.xml"
+ xpointer="configuration-variable-list" />
</appendix>
<xi:include href="release-notes/release-notes.xml" />
diff --git a/nixos/doc/manual/options-to-docbook.xsl b/nixos/doc/manual/options-to-docbook.xsl
index 7b45b233ab2..43a69806a2b 100644
--- a/nixos/doc/manual/options-to-docbook.xsl
+++ b/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, '*', '_'), '<', '_'), '>', '_'), '?', '_'))" />
<varlistentry>
@@ -100,7 +100,7 @@
</xsl:for-each>
</variablelist>
-
+ </appendix>
</xsl:template>
diff --git a/nixos/release.nix b/nixos/release.nix
index 2f779280e6b..4994cd98302 100644
--- a/nixos/release.nix
+++ b/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;
From a77dc213a7825f5dd13c7989e38d82e64816d881 Mon Sep 17 00:00:00 2001
From: Graham Christensen <graham@grahamc.com>
Date: Sat, 28 Apr 2018 04:04:56 -0400
Subject: [PATCH 3/4] nixos manual: update xi:include for configuruation.nix's
options-db
---
nixos/doc/manual/man-configuration.xml | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/nixos/doc/manual/man-configuration.xml b/nixos/doc/manual/man-configuration.xml
index 89d321d6972..37ffb9d648a 100644
--- a/nixos/doc/manual/man-configuration.xml
+++ b/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="./generated/options-db.xml" />
+<xi:include href="./generated/options-db.xml"
+ xpointer="configuration-variable-list" />
</refsection>
From 74fcb1c770e3a5178a7ee089b3caf406f7bf94bf Mon Sep 17 00:00:00 2001
From: Graham Christensen <graham@grahamc.com>
Date: Sat, 28 Apr 2018 04:15:16 -0400
Subject: [PATCH 4/4] nixos docs: include note about make for debugging the
nixos docs
---
.../development/writing-documentation.xml | 22 ++++++++++++++-----
1 file changed, 17 insertions(+), 5 deletions(-)
diff --git a/nixos/doc/manual/development/writing-documentation.xml b/nixos/doc/manual/development/writing-documentation.xml
index 59a287717ac..8b787fae1fe 100644
--- a/nixos/doc/manual/development/writing-documentation.xml
+++ b/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