about summary refs log tree commit diff
path: root/nixos/doc/manual/default.nix
AgeCommit message (Collapse)AuthorFilesLines
2019-10-30nixos manual: have a toc for each part and chapterFrederik Rietdijk1-1/+0
to be inline with the Nixpkgs manual. This makes navigating to particular sections easier.
2019-10-30nixos manual: reduce toc depthFrederik Rietdijk1-1/+1
to reduce the amount of information presented.
2019-08-08Extract NixOS options documentation generation to a functionDomen Kožar1-97/+9
Motivation is to support other repositories containing nixos modules that would like to generate options documentation: - nix-darwin - private repos - arion - ??
2019-03-09Merge pull request #55436 from layus/warn-manual-idsGraham Christensen1-1/+4
Nixos manual: error out on missing IDs
2019-03-05nixos: doc: increase maxdepth for xsltprocJan Malakhovski1-0/+1
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-02-08nixos/manual: error out on missing IDsGuillaume Maudoux1-1/+4
2019-02-07nixos/manual: warn on missing xml:idGuillaume Maudoux1-0/+1
2018-09-23nixos: doc: rename `manual` to `manualHTML`, cleanup referencesJan Malakhovski1-1/+6
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-02nixos: Split paras by \n\n in option descriptionsaszlig1-1/+3
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-07-18treewide: remove aliases in nixpkgsMatthew Bauer1-7/+7
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-06-13nixos: doc: make `relatedPackages` a bit smarterJan Malakhovski1-2/+3
2018-04-28nixos docs: Add a makefile for hacking on the nixos docsGraham Christensen1-0/+1
2018-04-27nixos docs: Move generated XML in to a specific subdirectory to allow easier ↵Graham Christensen1-3/+8
hacking
2018-04-05nixos docs: syntax highlightGraham Christensen1-5/+8
- 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-03-21nixos/manual: Don't depend on non-bin outputs of libxml2 and libxsltTuomas Tynkkynen1-5/+5
Might fix https://hydra.nixos.org/build/71580290.
2018-03-01nixos: manual: Fix cross-compilation.Shea Levy1-5/+5
2018-02-18stdenv.mkDerivation: rename `meta.evaluates` -> `meta.available`Jan Malakhovski1-1/+1
A much better name.
2018-02-11nixos: doc: trivial cleanup and docstring fixJan Malakhovski1-3/+3
2018-02-11nixos: doc: make option sorting somewhat more efficientJan Malakhovski1-3/+2
2018-02-09nixos, lib: implement relatedPackages optionJan Malakhovski1-2/+32
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-09nixos/doc: push all the `enable*' and `package*` options to the top of their ↵Jan Malakhovski1-4/+18
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-01-31Add setFunctionArgs lib function.Shea Levy1-1/+1
Among other things, this will allow *2nix tools to output plain data while still being composable with the traditional callPackage/.override interfaces.
2017-12-23Revert "nixos: doc: implement related packages in the manual"Graham Christensen1-31/+3
2017-12-07nixos, lib: implement relatedPackages optionJan Malakhovski1-2/+16
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-07nixos/doc: push all the `enable*' and `package*` options to the top of their ↵Jan Malakhovski1-1/+15
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-11-22nixos/doc/manual: print context on failing xmllint validationProfpatsch1-7/+37
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-06-29nixos manual: combine XML and validate separatelyGraham Christensen1-35/+34
2017-06-28nixos manual: Remove trailing newline in version XMLGraham Christensen1-1/+1
2016-09-29NixOS: Use runCommand instead of mkDerivation in a few placesEelco Dolstra1-49/+28
2016-08-30nixos manual: cleanup generationEric Sagnes1-6/+0
2016-08-11manual: automatically generate modules entriesEric Sagnes1-1/+10
2016-08-02nixos manual: add Emacs section (fixes #13217)Rodney Lorrimar1-0/+1
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-01Fix epub generationEelco Dolstra1-3/+6
* 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-01Remove the PDF manualEelco Dolstra1-24/+1
PDF is very 20th century and nobody reads technical documentation this way anymore.
2016-07-28add epub for NixOS manual (second try) (#17205)Christine Koppelt1-10/+47
2016-05-02Merge pull request #14700: olinks for NixOS manualaszlig1-13/+62
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-04-15Merge pull request #14476 (taskserver)aszlig1-0/+1
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-14nixos/doc: Revert allowing olinks from optionsaszlig1-62/+13
This reverts commit 1d77dcaed37ab47bfe2d90711c01b475a514ff25. 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-14nixos/doc: Allow refs from options to the manualaszlig1-13/+62
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-13Merge branch 'staging', containing closure-size #7701Vladimír Čunát1-1/+1
2016-04-12input-method module: fix folder caseEric Sagnes1-1/+1
2016-04-12manual: add chapter on input methodsEric Sagnes1-0/+1
2016-04-11nixos/doc: Allow refs from options to the manualaszlig1-13/+62
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-07nixos/taskserver: Add module documentationaszlig1-0/+1
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-01Merge branch 'master' into closure-sizeVladimír Čunát1-0/+1
Beware that stdenv doesn't build. It seems something more will be needed than just resolution of merge conflicts.
2016-03-19nixos/manpages: enable linebreaking after slashesPascal Wittmann1-0/+1
Allow linbreaks after slashes in long URLs. The option used is documented at http://docbook.sourceforge.net/release/xsl/current/doc/manpages/man.break.after.slash.html This commit fixes #4538.
2016-03-08Merge master into closure-sizeVladimír Čunát1-1/+1
The kde-5 stuff still didn't merge well. I hand-fixed what I saw, but there may be more problems.
2016-03-01Revert "Add the tool "nixos-typecheck" that can check an option declaration to:"Eelco Dolstra1-4/+2
This reverts commit cad8957eabcbf73062226d28366fd446c15c8737. It breaks NixOps, but more importantly, such major changes to the module system really need to be reviewed.
2016-02-29Add the tool "nixos-typecheck" that can check an option declaration to:Thomas Strobel1-2/+4
- Enforce that an option declaration has a "defaultText" if and only if the type of the option derives from "package", "packageSet" or "nixpkgsConfig" and if a "default" attribute is defined. - Enforce that the value of the "example" attribute is wrapped with "literalExample" if the type of the option derives from "package", "packageSet" or "nixpkgsConfig". - Warn if a "defaultText" is defined in an option declaration if the type of the option does not derive from "package", "packageSet" or "nixpkgsConfig". - Warn if no "type" is defined in an option declaration.
2016-02-27Revert "Add a way to pin a NixOS version within the module system."Eelco Dolstra1-1/+0
This reverts commit a5992ad61b314104aff7e28a41ce101a1b0e7c35. Motivation: https://github.com/NixOS/nixpkgs/commit/a5992ad61b314104aff7e28a41ce101a1b0e7c35#commitcomment-14986820