Commit Graph

48 Commits

Author SHA1 Message Date
Robert Hensing
5b52d552cb nixos/make-options-doc: Explain docbook to markdown migration 2022-09-17 13:38:23 +01:00
pennae
767485a0de lib/options: deprecate docbook text and literalDocBook
deprecate literalDocBook by adding a warning (that will not fire yet) to
its uses and other docbook literal strings by adding optional warning
message to mergeJSON.
2022-09-10 18:23:13 +02:00
pennae
9c3c13b50d nixos/make-options-doc: add inline roles for varname/envar
both of these render distinctly from plain literals in the manpage, and
manpages even semantically distinguish between the two.
2022-08-31 16:21:10 +02:00
pennae
65fd6f0774 nixos/make-options-doc: eat newlines in MD admonitions
leaving some newlines around after an admonition was closed causes the
newline rule to match, which in turn inserts literallayout newlines into
te xml output. that's not what we want.
2022-08-27 19:18:29 +02:00
Robert Schütz
243053e521 python310Packages.mistune: 0.8.4 -> 2.0.4
Remove mistune_0_8 because it's insecure.
2022-08-15 06:53:01 +00:00
pennae
af98bacbe0 Revert "nixos/docs: cache mergeJSON md conversion on baseOptionsJSON"
This reverts commit 52b0ad17e3.

we only needed this because mergeJSON was slow, but in the interim we
found a better solution to the slowness.
2022-08-05 17:13:47 +02:00
pennae
645cfa59ac nixos/make-option-docs: add xref support to markdown conversion 2022-08-03 22:01:14 +02:00
pennae
7a091b2686 nixos/make-options-doc: reuse markdown instance in mergeJSON
this doesn't construct a new (expensive) parser for every option, making
rendering about 30x faster.
2022-08-03 22:00:24 +02:00
pennae
52b0ad17e3 nixos/docs: cache mergeJSON md conversion on baseOptionsJSON
with ever more options being markdown rather than docbook the conversion
time is starting to become a significant factor of doc build time.
luckily we can pre-convert all nixos option docs to MD and cache the
result of this conversion, then merge the already-converted json file
with user option docs. we leave options.json unconverted to keep it as
close to the actual nix code as possible.
2022-07-28 23:20:02 +02:00
pennae
18be724a58 nixos/make-options-doc: give MD conversion error locations
during docs conversion it can be very useful to know exactly *where* the
error the script complained about is. the name of the option should be
sufficient since option merging is rather rare, and won't merge doc
attributes anyway.
2022-07-28 20:03:02 +02:00
Robert Hensing
7c81905344 nixos/make-options-doc: Support Nix-provided declaration locations
Feature was introduced in https://github.com/NixOS/nixpkgs/pull/174460,
but wasn't supported in `mergeJSON.py` yet.
2022-06-27 22:07:20 +02:00
Robert Hensing
8bff3fef40 nixos/make-options-doc: Support block quotes
Our tooling would trip without the inner <para>, despite the docbook
docs suggesting that <para> occurs in <blockquote> and vice versa.
2022-06-27 17:41:32 +02:00
Robert Hensing
e04aa1bcd9 nixos/make-options-doc: Escape inline code and code blocks 2022-06-27 17:41:32 +02:00
Robert Hensing
f900ed1749 nixos/make-options-doc: Support newline md node
This occurs in the ast generated for blockquotes.
2022-06-27 17:41:32 +02:00
Robert Hensing
bccc3e747b nixos/make-options-doc: Fix exception handler for arity /= 1 methods 2022-06-27 17:41:32 +02:00
Robert Hensing
aff2dbbc82 make-options-doc: Make variablelist id configurable
I've tried XInclude set-xml-id first, but our tooling did not pick up on it.
2022-06-27 17:41:32 +02:00
Robert Hensing
fa9c83ca7f
Merge pull request #174460 from hercules-ci/module-docs-Nix-driven-location-links
make-options-doc: Support Nix-provided declaration links
2022-06-22 15:48:46 +02:00
Robert Hensing
cee66a8cd5 make-options-doc: Support Nix-provided declaration links
Previously, the location logic was hardcoded, supporting only
Nixpkgs and NixOps properly, leaving other uses of the module
system without good location support.
2022-06-15 00:45:05 +02:00
pennae
320aa2a791 treewide: attempt at markdown option docs 2022-06-12 12:44:38 +02:00
Robert Hensing
75bc6da237 make-options-doc: Filter options after transformOptions
This allows the user-supplied function to change the visibility
of options.
2022-05-25 12:50:07 +02:00
Robert Hensing
90344e9f40
Merge pull request #171163 from hercules-ci/nixpkgs-config-doc
Add generated `nixpkgs.config` doc to Nixpkgs manual
2022-05-19 20:51:38 +02:00
Robert Hensing
0b02135d3b nixosOptionsDoc: refactor
Thanks to Infinisil for pointing this out.
2022-05-16 22:53:23 +02:00
Robert Hensing
062bc5e74a lib.types.functionTo: Add pseudo-attr to generated docs 2022-05-13 09:01:05 +02:00
Robert Hensing
bb2c5a3684 nixosOptionsDoc: Make appendix tag optional 2022-05-01 21:51:19 +02:00
Silvan Mosberger
25de2935ef lib/modules: Document _module.args
Documents the _module.args option, motivated by many usages in Flakes,
especially with the deprecation of extraArgs
(78ada83361)

The documentation rendering for this option had to be handled a bit
specially, since it's not declared in nixos/modules like all the other
NixOS options.

Co-Authored-By: pennae <github@quasiparticle.net>
Co-Authored-By: Robert Hensing <robert@roberthensing.nl>
2022-04-05 18:26:40 +02:00
Janne Heß
0c766a100e lib/options: Throw error for options without a type
Makes all options rendered in the manual throw an error if they don't
have a type specified.

This is a follow-up to #76184

Co-Authored-By: Silvan Mosberger <contact@infinisil.com>
2022-02-28 22:51:41 +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
1301bdb185 nixos/make-options-doc: turn relatedPackages into links
link to search.nixos.org instead of pulling package metadata out of pkgs. this
lets us cache docs of a few more modules and provides easier access to package
info from the HTML manual, but makes the manpage slightly less useful since
package description are no longer rendered.
2022-01-02 19:46:13 +01:00
pennae
b92a47c87c nixos/make-options-doc: add type annotations to mergeJSON.py 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
Julien Moutinho
8b842173d0 nixos/make-options-doc: fix invalid ':' in XML NCName (non-colonized name) 2021-12-28 22:18:16 -05:00
pennae
a70b1eb630 nixos/lib/make-options-doc: fix with nix 2.3 2021-12-14 03:41:09 +01:00
pennae
027f7e1b7f nixos/lib/make-options-doc: generate options.xml from options.json
to do this we must replace derivations with attrsets in make-options-doc, since
xml can represent derivations differently from attrset but json cannot. this
also given asciidoc and mddoc the ability to handle derivation differently,
which they previously didn't have.
2021-12-06 16:12:32 +01:00
pennae
9b97a2ea88 nix/lib/make-options-doc: remove nix-level sorting
there are no remaining users of sorted option lists except the docbook build,
which sorts its input separately.
2021-12-06 16:12:32 +01:00
pennae
4670400309 nixos/lib/make-options-doc: generate asciidoc/md in derivations
use the json file derivation we already have to also generate the asciidoc and
md options docs instead of formatting the options in nix. docbook docs are
already produced in derivations.

the new script produce the exact same output as the old in-nix generation.
2021-12-06 16:12:30 +01:00
pennae
24eb353907 make-options-docs: don't sort the options XML file
we need the file itself as a dependency for the docbook build, but we don't need
it to be properly sorted at the nix level. push the sort out to a python script
instead to save eval time. on the machine used to write this `nix-instantiate
<nixos/nixos> -A system` went down from 7.1s to 5.4s and GC heap size decreased
by 50MB (or 70MB max RSS).
2021-10-18 03:45:33 +02:00
Naïm Favier
330b1e08b8
nixos/lib/make-options-doc: implement literalDocBook 2021-10-03 17:59:44 +02:00
Pacman99
d12aba5406 nixosOptionsDoc: add markdown formatting 2021-04-13 10:10:40 -07:00
rnhmjoj
3f8a3246f4
nixos/lib/make-options-doc: remove loaOf subs
Remove the substitution for the <name?> placeholder used by loaOf,
now that the type has been deprecated.
2020-09-02 00:42:51 +02:00
Maximilian Bosch
6d19c04416
nixos/manual: improve error message for invalid values in `relatedPackages'
As reported in NixOS discourse[1], tracking down invalid values in
`relatedPackages'[2] (i.e. list-items that don't exist in `pkgs`) is
fairly hard as the message "Invalid package attribute path `foobar'"
is quite unhelpful and the trace doesn't point to the source of the
problem either.

This patch improves the error message by mentioning that the issue is an
invalid `relatedPackages`-declaration in $optionName.

[1] https://discourse.nixos.org/t/invalid-package-attribute-path-nextcloud19/8403/9
[2] https://nixos.org/nixpkgs/manual/#sec-functions-library-options
2020-08-03 16:37:59 +02:00
Jan Tojnar
cab6b019b1
Revert "make-options-doc: fix string context issues"
This reverts commit 3c15d578d4.

See https://github.com/NixOS/nixpkgs/issues/83863
2020-04-02 00:53:54 +02:00
Eelco Dolstra
4052f9b849
Compress optionsJSON using brotli 2020-03-24 16:42:04 +01:00
Dima
3c15d578d4 make-options-doc: fix string context issues
When using `documentation.nixos.includeAllModules = true;` with external
modules, the string context might contain dependencies to derivations
and so `toFile` refuses to evaluate;

```
error: in 'toFile': the file 'options.xml' cannot refer to derivation outputs, at
[...]/nixpkgs/nixos/lib/make-options-doc/default.nix:89:16
```

This is not an issue when using `writeText` (instead of manually
stripping the context).
2019-11-23 15:40:45 +01:00
volth
08f68313a4 treewide: remove redundant rec 2019-08-28 11:07:32 +00:00
Domen Kožar
dcd50c0ea0
pkgs.lib -> lib 2019-08-12 11:46:53 +02:00
Domen Kožar
6cf861c617
make-options-doc: add asciidoc variant 2019-08-10 20:11:04 +02:00
Domen Kožar
3a93fcfd1e
make-options-doc: expose Nix set 2019-08-10 14:24:11 +02: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