Commit graph

96 commits

Author SHA1 Message Date
pennae 9d3ba92d63 nixos/documentation: fix docs cross build
a few things should've used buildPackages/nativeBuildInputs to not not require
the host architecture for building docs. tested by building aarch64-linux docs
on x86_64-linux, and the result looks good.
2022-01-08 16:03:23 +01:00
pennae 50954ad1c5 nixos/make-options-doc: treat missing descriptions as errors by default
this partially solves the problem of "missing description" warnings of the
options doc build being lost by nix build, at the cost of failing builds that
previously ran. an option to disable this behaviour is provided.
2022-01-02 19:46:13 +01:00
pennae fc614c37c6 nixos/documentation: split options doc build
most modules can be evaluated for their documentation in a very
restricted environment that doesn't include all of nixpkgs. this
evaluation can then be cached and reused for subsequent builds, merging
only documentation that has changed into the cached set. since nixos
ships with a large number of modules of which only a few are used in any
given config this can save evaluation a huge percentage of nixos
options available in any given config.

in tests of this caching, despite having to copy most of nixos/, saves
about 80% of the time needed to build the system manual, or about two
second on the machine used for testing. build time for a full system
config shrank from 9.4s to 7.4s, while turning documentation off
entirely shortened the build to 7.1s.
2022-01-02 19:46:13 +01:00
pennae c533b01863 nixos/doc/manual: remove non-matching optionsXML inherit 2021-12-06 16:12:32 +01:00
Ben Siraphob 1c2a2b0a08 treewide: fold -> foldr 2021-01-26 10:57:07 +07:00
zimbatm 7d834eff6c
nixos/manual: make reproducible (#102234) 2020-10-31 21:18:16 +01:00
Frederik Rietdijk 70bb2e4151 nixos manual: have a toc for each part and chapter
to be inline with the Nixpkgs manual. This makes navigating to
particular sections easier.
2019-10-30 10:25:09 +01:00
Frederik Rietdijk 227dff4e70 nixos manual: reduce toc depth
to reduce the amount of information presented.
2019-10-30 10:25:09 +01:00
Domen Kožar 5cfd034af0
Extract NixOS options documentation generation to a function
Motivation is to support other repositories containing nixos
modules that would like to generate options documentation:

- nix-darwin
- private repos
- arion
- ??
2019-08-08 16:18:09 +02:00
Graham Christensen 777e94d903
Merge pull request #55436 from layus/warn-manual-ids
Nixos manual: error out on missing IDs
2019-03-09 08:21:07 -05:00
Jan Malakhovski ca496b194f nixos: doc: increase maxdepth for xsltproc
See https://github.com/NixOS/nixpkgs/issues/37903#issuecomment-376618117
for details. With the previous patch and some custom modules included in
`configuration.nix` the above bug is very easy to trigger.

This is a simplest workaround I have. A proper solution would look like
https://github.com/NixOS/nixpkgs/issues/37903#issuecomment-376980838.
2019-03-05 09:41:40 +00:00
Guillaume Maudoux a65974c604 nixos/manual: error out on missing IDs 2019-02-08 10:59:46 +01:00
Guillaume Maudoux 4c0230eb56 nixos/manual: warn on missing xml:id 2019-02-07 16:35:24 +01:00
Jan Malakhovski fe744d3fb1 nixos: doc: rename manual to manualHTML, cleanup references
Because when I see "config.system.build.manual.manual" after I forgot
what it means I ask "Why do I need that second `.manual` there again?".
Doesn't happen with `config.system.build.manual.manualHTML`.
2018-09-23 20:47:58 +00:00
aszlig f865d0feab
nixos: Split paras by \n\n in option descriptions
What annoyed me for a long time was the fact, that in order to break
into a new paragraph, you need to insert </para><para> in the
description attribute of an option.

Now we will automatically create <para/> elements for every block that
is separated by two consecutive newlines.

I first tried to do this within options-to-docbook.xsl, but it turns
out[1] that this isn't directly possible with XSLT 1.0, so I added
another XSLT file that postprocesses the option descriptions that are
now enclosed in <nixos:option-description/> by options-to-docbook.xsl.

The splitting itself is a bit more involved, because we can't simply
split on every \n\n because we'd also split text nodes of elements, for
example:

  <screen><![CDATA[

    one line

    another one

  ]]></screen>

This would create one <para/> element for "one line" and another for
"another line", which we obviously don't want because <screen/> is used
to display verbatim contents of what a user is seeing on the screen.

So what we do instead is splitting *only* the top-level text nodes
within the outermost <para/> and leave all elements as-is. If there are
more than one <para/> elements at the top-level, we simply don't process
it at all, because the description then already contains </para><para>.

https://www.mhonarc.org/archive/html/xsl-list/2012-09/msg00319.html

Signed-off-by: aszlig <aszlig@nix.build>
Cc: @edolstra, @domenkozar
2018-09-02 08:10:37 +02:00
Matthew Bauer 76999cc40e treewide: remove aliases in nixpkgs
This makes the command ‘nix-env -qa -f. --arg config '{skipAliases =
true;}'’ work in Nixpkgs.

Misc...

- qtikz: use libsForQt5.callPackage

  This ensures we get the right poppler.

- rewrites:

  docbook5_xsl -> docbook_xsl_ns
  docbook_xml_xslt -> docbook_xsl

diffpdf: fixup
2018-07-18 23:25:20 -04:00
Jan Malakhovski 2a5688574c nixos: doc: make relatedPackages a bit smarter 2018-06-13 16:25:10 +00:00
Graham Christensen 0ff0d138e4
nixos docs: Add a makefile for hacking on the nixos docs 2018-04-28 04:00:55 -04:00
Graham Christensen 59f8b1e844
nixos docs: Move generated XML in to a specific subdirectory to allow easier hacking 2018-04-27 22:44:51 -04:00
Graham Christensen 8f33464ca7
nixos docs: syntax highlight
- Rectifies diverging CSS by combining
   nixos/nixpkgs docs CSS
 - Moves our custom Highlight.js loader in to
   the hljs package
 - Switches the nixos docs to use SVG
   callouts too
2018-04-05 07:54:01 -04:00
Tuomas Tynkkynen 3918182cb5 nixos/manual: Don't depend on non-bin outputs of libxml2 and libxslt
Might fix https://hydra.nixos.org/build/71580290.
2018-03-21 22:18:49 +02:00
Shea Levy 20072d733b
nixos: manual: Fix cross-compilation. 2018-03-01 10:41:50 -05:00
Jan Malakhovski 810c4702cf stdenv.mkDerivation: rename meta.evaluates -> meta.available
A much better name.
2018-02-18 13:33:25 +00:00
Jan Malakhovski b468f98b02 nixos: doc: trivial cleanup and docstring fix 2018-02-11 22:41:06 +00:00
Jan Malakhovski 252ec7da0a nixos: doc: make option sorting somewhat more efficient 2018-02-11 22:07:11 +00:00
Jan Malakhovski 660806066a nixos, lib: implement relatedPackages option
This allows one to specify "related packages" in NixOS that get rendered into
the configuration.nix(5) man page. The interface philosophy is pretty much
stolen from TeX bibliography.

See the next several commits for examples.
2018-02-09 19:51:06 +00:00
Jan Malakhovski a7d75ab648 nixos/doc: push all the enable*' and package*` options to the top of their option group
Why? Because this way configuration.nix(5) can be read linearly.

Before:

> virtualisation.xen.bootParams
> ...
> virtualisation.xen.enable
> ...
> virtualisation.xen.package
> ...

After:

> virtualisation.xen.enable
> virtualisation.xen.package
> virtualisation.xen.bootParams
> ...
2018-02-09 19:51:05 +00:00
Shea Levy 943592f698
Add setFunctionArgs lib function.
Among other things, this will allow *2nix tools to output plain data
while still being composable with the traditional
callPackage/.override interfaces.
2018-01-31 14:02:19 -05:00
Graham Christensen b5a61f2c59
Revert "nixos: doc: implement related packages in the manual" 2017-12-23 07:19:45 -05:00
Jan Malakhovski 67ec6371d5 nixos, lib: implement relatedPackages option
This allows one to specify "related packages" in NixOS that get rendered into
the configuration.nix(5) man page. The interface philosophy is pretty much
stolen from TeX bibliography.
2017-12-07 21:26:35 +00:00
Jan Malakhovski 182463dc79 nixos/doc: push all the enable*' and package*` options to the top of their option group
Why? Because this way configuration.nix(5) can be read linearly.

Before:

> virtualisation.xen.bootParams
> ...
> virtualisation.xen.enable
> ...
> virtualisation.xen.package
> ...

After:

> virtualisation.xen.enable
> virtualisation.xen.package
> virtualisation.xen.bootParams
> ...
2017-12-07 21:26:34 +00:00
Profpatsch f09f49d483 nixos/doc/manual: print context on failing xmllint validation
Previously only the line numbers of a giant, internally generated XML file were
printed, without any kind of debuggability.
Now at least the mentioned lines are printed with a little bit of surrounding
context (to have something to grep for).

```
manual-combined.xml:4863: element para: Relax-NG validity error : Did not expect element para there
  4859	<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-modules">
  4860
  4861	<title>Writing NixOS Modules</title>
  4862
  4863	<para>NixOS has a modular system for declarative configuration.  This
  4864	system combines multiple <emphasis>modules</emphasis> to produce the
  4865	full system configuration.  One of the modules that constitute the
```
2017-11-22 21:27:05 +01:00
Graham Christensen 1eb979db0e
nixos manual: combine XML and validate separately 2017-06-29 11:25:03 -04:00
Graham Christensen 4f3f926906
nixos manual: Remove trailing newline in version XML 2017-06-28 19:58:06 -04:00
Eelco Dolstra 75a1ec8a65 NixOS: Use runCommand instead of mkDerivation in a few places 2016-09-29 13:05:28 +02:00
Eric Sagnes b50e627ef6 nixos manual: cleanup generation 2016-08-30 09:40:05 +09:00
Eric Sagnes 898435d16e manual: automatically generate modules entries 2016-08-11 00:24:41 +09:00
Rodney Lorrimar 6711e62d51 nixos manual: add Emacs section (fixes #13217)
In light of Emacs packaging improvements such as those mentioned
in #11503, and with the addition of a systemd service (#15807
and #16356), and considering that the wiki page is completely
out of date (#13217), it seems that some documentation is in order.
2016-08-02 11:17:52 +01:00
Eelco Dolstra 0804f67024 Fix epub generation
* Hydra doesn't like spaces in filenames.

* The zip file contained nix/store/.../OEBPS rather than OEBPS at
  top-level, causing some programs (like okular) to barf.

* Remove the redundant $dst/epub directory.
2016-08-01 11:10:22 +02:00
Eelco Dolstra d5756cdf0a Remove the PDF manual
PDF is very 20th century and nobody reads technical documentation this
way anymore.
2016-08-01 11:10:21 +02:00
Christine Koppelt 39da575262 add epub for NixOS manual (second try) (#17205) 2016-07-28 04:27:39 +02:00
aszlig d2c64031a0
Merge pull request #14700: olinks for NixOS manual
This allows to use <olink> tags inside NixOS options to reference
sections from the manual. I've originally introduced it in #14476 to
reference the Taskserver specific documentation from the options
reference but as suggested by @nbp, this was done as a separate pull
request to ensure greater visibility rather than being "hidden" in the
Taskserver branch.

The build time for the manual is around 30s on my machine without this
change and 34s with this change, so it shouldn't have a very big impact
on the build time of the manual.

Olinks between the options reference and the manual now will look like
this:

"More instructions about NixOS in conjuction with Taskserver can be
found in the NixOS manual at Chapter 15, Taskserver."

More documentation about olinks can be found here:

http://www.sagehill.net/docbookxsl/Olinking.html

Acked-by: Eelco Dolstra <eelco.dolstra@logicblox.com>
2016-05-02 11:01:13 +02:00
aszlig 9ed9e268a2
Merge pull request #14476 (taskserver)
This adds a Taskserver module along with documentation and a small
helper tool which eases managing a custom CA along with Taskserver
organisations, users and groups.

Taskserver is the server component of Taskwarrior, a TODO list
application for the command line.

The work has been started by @matthiasbeyer back in mid 2015 and I have
continued to work on it recently, so this merge contains commits from
both of us.

Thanks particularly to @nbp and @matthiasbeyer for reviewing and
suggesting improvements.

I've tested this with the new test (nixos/tests/taskserver.nix) this
branch adds and it fails because of the changes introduced by the
closure-size branch, so we need to do additional work on base of this.
2016-04-15 00:21:49 +02:00
aszlig c36d6e5964
nixos/doc: Revert allowing olinks from options
This reverts commit 1d77dcaed3.

It will be reintroduced along with #14700 as a separate branch, as
suggested by @nbp.

I added this to this branch because I thought it was a necessary
dependency, but it turns out that the build of the manual/manpages still
succeeds and merely prints a warning like this:

warning: failed to load external entity "olinkdb.xml"
Olink error: could not open target database 'olinkdb.xml'.
Error: unresolved olink: targetdoc/targetptr = 'manual/module-taskserver'.

The olink itself will be replaced by "???", so users looking at the
description of the option in question will still see the reference to
the NixOS manual, like this:

More instructions about NixOS in conjuction with Taskserver can be found
in the NixOS manual at ???.

Signed-off-by: aszlig <aszlig@redmoonstudios.org>
2016-04-14 21:31:02 +02:00
aszlig 41f170f439
nixos/doc: Allow refs from options to the manual
My first attempt to do this was to just use a conditional <refsection/>
in order to not create exact references in the manpage but create the
reference in the HTML manual, as suggested by @edolstra on IRC.

Later I went on to use <olink/> to reference sections of the manual, but
in order to do that, we need to overhaul how we generate the manual and
manpages.

So, that's where we are now:

There is a new derivation called "manual-olinkdb", which is the olinkdb
for the HTML manual, which in turn creates the olinkdb.xml file and the
manual.db. The former contains the targetdoc references and the latter
the specific targetptr elements.

The reason why I included the olinkdb.xml verbatim is that first of all
the DTD is dependent on the Docbook XSL sources and the references
within the olinkdb.xml entities are relative to the current directory.

So using a store path for that would end up searching for the manual.db
directly in /nix/store/manual.db.

Unfortunately, the <olinks/> that end up in the output file are
relative, so for example if you're clicking on one of these within the
PDF, the URL is searched in the current directory.

However, the sections from the olink's text are still valid, so we could
use an alternative URL for that in the future.

The manual doesn't contain any links, so even referencing the relative
URL shouldn't do any harm.

Signed-off-by: aszlig <aszlig@redmoonstudios.org>
Cc: @edolstra
2016-04-14 21:24:50 +02:00
Vladimír Čunát 39ebb01d6e Merge branch 'staging', containing closure-size #7701 2016-04-13 09:25:28 +02:00
Eric Sagnes e6ae05dd8a input-method module: fix folder case 2016-04-12 19:50:26 +09:00
Eric Sagnes de78fe8f2d manual: add chapter on input methods 2016-04-12 19:50:16 +09:00
aszlig 1d77dcaed3
nixos/doc: Allow refs from options to the manual
My first attempt to do this was to just use a conditional <refsection/>
in order to not create exact references in the manpage but create the
reference in the HTML manual, as suggested by @edolstra on IRC.

Later I went on to use <olink/> to reference sections of the manual, but
in order to do that, we need to overhaul how we generate the manual and
manpages.

So, that's where we are now:

There is a new derivation called "manual-olinkdb", which is the olinkdb
for the HTML manual, which in turn creates the olinkdb.xml file and the
manual.db. The former contains the targetdoc references and the latter
the specific targetptr elements.

The reason why I included the olinkdb.xml verbatim is that first of all
the DTD is dependent on the Docbook XSL sources and the references
within the olinkdb.xml entities are relative to the current directory.

So using a store path for that would end up searching for the manual.db
directly in /nix/store/manual.db.

Unfortunately, the <olinks/> that end up in the output file are
relative, so for example if you're clicking on one of these within the
PDF, the URL is searched in the current directory.

However, the sections from the olink's text are still valid, so we could
use an alternative URL for that in the future.

The manual doesn't contain any links, so even referencing the relative
URL shouldn't do any harm.

Signed-off-by: aszlig <aszlig@redmoonstudios.org>
Cc: @edolstra
2016-04-11 18:38:04 +02:00
aszlig 64e566a49c
nixos/taskserver: Add module documentation
It's not by any means exhaustive, but we're still going to change the
implementation, so let's just use this as a starting point.

Signed-off-by: aszlig <aszlig@redmoonstudios.org>
2016-04-07 14:26:12 +02:00