diff options
author | Graham Christensen <graham@grahamc.com> | 2018-04-29 21:56:45 -0400 |
---|---|---|
committer | GitHub <noreply@github.com> | 2018-04-29 21:56:45 -0400 |
commit | 8caaec894ebfe0cc9866f86e244f67d0607c2653 (patch) | |
tree | 263944f3fca09d4935b121ddc9729ab4e21c47a0 | |
parent | f148c5c4a1ffa353836bfd18a94d457acf83bd36 (diff) | |
parent | 74fcb1c770e3a5178a7ee089b3caf406f7bf94bf (diff) | |
download | nixlib-8caaec894ebfe0cc9866f86e244f67d0607c2653.tar nixlib-8caaec894ebfe0cc9866f86e244f67d0607c2653.tar.gz nixlib-8caaec894ebfe0cc9866f86e244f67d0607c2653.tar.bz2 nixlib-8caaec894ebfe0cc9866f86e244f67d0607c2653.tar.lz nixlib-8caaec894ebfe0cc9866f86e244f67d0607c2653.tar.xz nixlib-8caaec894ebfe0cc9866f86e244f67d0607c2653.tar.zst nixlib-8caaec894ebfe0cc9866f86e244f67d0607c2653.zip |
Merge pull request #39649 from grahamc/hacking-docs
NixOS docs: making it easier to hack on
-rw-r--r-- | nixos/doc/manual/Makefile | 8 | ||||
-rw-r--r-- | nixos/doc/manual/configuration/configuration.xml | 3 | ||||
-rw-r--r-- | nixos/doc/manual/default.nix | 12 | ||||
-rw-r--r-- | nixos/doc/manual/development/writing-documentation.xml | 20 | ||||
-rw-r--r-- | nixos/doc/manual/man-configuration.xml | 3 | ||||
-rw-r--r-- | nixos/doc/manual/manual.xml | 5 | ||||
-rw-r--r-- | nixos/doc/manual/options-to-docbook.xsl | 8 | ||||
-rw-r--r-- | nixos/release.nix | 2 |
8 files changed, 44 insertions, 17 deletions
diff --git a/nixos/doc/manual/Makefile b/nixos/doc/manual/Makefile new file mode 100644 index 000000000000..b15fbaa270fc --- /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/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml index 8677c13db40f..f092c7e207ff 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 ac22712baf87..2c6309474b37 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" @@ -224,6 +229,7 @@ let ''; in rec { + inherit generatedSources; # The NixOS options in JSON format. optionsJSON = runCommand "options-json" diff --git a/nixos/doc/manual/development/writing-documentation.xml b/nixos/doc/manual/development/writing-documentation.xml index 59a287717acb..8b787fae1fe0 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: + subdirectory of the Nixpkgs repository. +</para> - <screen>nix-build nixos/release.nix -A manual.x86_64-linux</screen> +<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 diff --git a/nixos/doc/manual/man-configuration.xml b/nixos/doc/manual/man-configuration.xml index 05531b3909a3..37ffb9d648a9 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="options-db.xml" /> +<xi:include href="./generated/options-db.xml" + xpointer="configuration-variable-list" /> </refsection> diff --git a/nixos/doc/manual/manual.xml b/nixos/doc/manual/manual.xml index 9aa332f026da..676924e5c8b2 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,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" /> diff --git a/nixos/doc/manual/options-to-docbook.xsl b/nixos/doc/manual/options-to-docbook.xsl index 7b45b233ab2a..43a69806a2b0 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 2f779280e6b2..4994cd98302f 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; |