pyrox.dev
1# Contributing to the Nixpkgs reference manual
2
3This directory houses the source files for the Nixpkgs reference manual.
4
5> [!IMPORTANT]
6> We are actively restructuring our documentation to follow the [Diátaxis framework](https://diataxis.fr/)
7>
8> Going forward, this directory should **only** contain [reference documentation](https://nix.dev/contributing/documentation/diataxis#reference).
9> For tutorials, guides and explanations, contribute to <https://nix.dev/> instead.
10>
11> We are actively working to generate **all** reference documentation from the [doc-comments](https://github.com/NixOS/rfcs/blob/master/rfcs/0145-doc-strings.md) present in code.
12> This also provides the benefit of using `:doc` in the `nix repl` to view reference documentation locally on the fly.
13
14For documentation only relevant for contributors, use Markdown files next to the source and regular code comments.
15
16> [!TIP]
17> Feedback for improving support for parsing and rendering doc-comments is highly appreciated.
18> [Open an issue](https://github.com/NixOS/nixpkgs/issues/new?labels=6.topic%3A+documentation&title=Doc%3A+) to request bugfixes or new features.
19
20Rendered documentation:
21- [Unstable (from master)](https://nixos.org/manual/nixpkgs/unstable/)
22- [Stable (from latest release)](https://nixos.org/manual/nixpkgs/stable/)
23
24The rendering tool is [nixos-render-docs](../pkgs/by-name/ni/nixos-render-docs), sometimes abbreviated `nrd`.
25
26## Contributing to this documentation
27
28You can quickly check your edits with `nix-build`:
29
30```ShellSession
31$ cd /path/to/nixpkgs
32$ nix-build doc
33```
34
35If the build succeeds, the manual will be in `./result/share/doc/nixpkgs/manual.html`.
36
37### Development environment
38
39In order to reduce repetition, consider using tools from the provided development environment:
40
41Load it from the Nixpkgs documentation directory with
42
43```ShellSession
44$ cd /path/to/nixpkgs/doc
45$ nix-shell
46```
47
48To load the development utilities automatically when entering that directory, [set up `nix-direnv`](https://nix.dev/guides/recipes/direnv).
49
50Make sure that your local files aren't added to Git history by adding the following lines to `.git/info/exclude` at the root of the Nixpkgs repository:
51
52```
53/**/.envrc
54/**/.direnv
55```
56
57#### `devmode`
58
59Use [`devmode`](../pkgs/by-name/de/devmode/README.md) for a live preview when editing the manual.
60
61### Testing redirects
62
63Once you have a successful build, you can open the relevant HTML (path mentioned above) in a browser along with the anchor, and observe the redirection.
64
65Note that if you already loaded the page and *then* input the anchor, you will need to perform a reload.
66This is because browsers do not re-run client JS code when only the anchor has changed.
67
68## Syntax
69
70As per [RFC 0072](https://github.com/NixOS/rfcs/pull/72), all new documentation content should be written in [CommonMark](https://commonmark.org/) Markdown dialect.
71
72Additional syntax extensions are available, all of which can be used in NixOS option documentation.
73The following extensions are currently used:
74
75#### Tables
76
77Tables, using the [GitHub-flavored Markdown syntax](https://github.github.com/gfm/#tables-extension-).
78
79#### Anchors
80
81Explicitly defined **anchors** on headings, to allow linking to sections.
82These should be always used, to ensure the anchors can be linked even when the heading text changes, and to prevent conflicts between [automatically assigned identifiers](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/auto_identifiers.md).
83
84It uses the widely compatible [header attributes](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/attributes.md) syntax:
85
86```markdown
87## Syntax {#sec-contributing-markup}
88```
89
90> [!Note]
91> NixOS option documentation does not support headings in general.
92
93#### Inline Anchors
94
95Allow linking to an arbitrary place in the text (e.g. individual list items, sentences…).
96
97They are defined using a hybrid of the link syntax with the attributes syntax known from headings, called [bracketed spans](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/bracketed_spans.md):
98
99```markdown
100- []{#ssec-gnome-hooks-glib} `glib` setup hook will populate `GSETTINGS_SCHEMAS_PATH` and then `wrapGApps*` hook will prepend it to `XDG_DATA_DIRS`.
101```
102
103#### Automatic links
104
105If you **omit a link text** for a link pointing to a section, the text will be substituted automatically.
106For example `[](#chap-contributing)`.
107
108This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing).
109
110
111#### HTML
112
113Inlining HTML is not allowed.
114Parts of the documentation gets rendered to various non-HTML formats, such as man pages in the case of NixOS manual.
115
116#### Roles
117
118If you want to link to a man page, you can use `` {manpage}`nix.conf(5)` ``.
119The references will turn into links when a mapping exists in [`doc/manpage-urls.json`](./manpage-urls.json).
120Please keep the `manpage-urls.json` file alphabetically sorted.
121
122A few markups for other kinds of literals are also available:
123
124- `` {command}`rm -rfi` ``
125- `` {env}`XDG_DATA_DIRS` ``
126- `` {file}`/etc/passwd` ``
127- `` {option}`networking.useDHCP` ``
128- `` {var}`/etc/passwd` ``
129
130These literal kinds are used mostly in NixOS option documentation.
131
132This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point).
133Though, the feature originates from [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-manpage) with slightly different syntax.
134They are handled by `myst_role` defined per renderer. <!-- reverse references in code -->
135
136#### Admonitions
137
138Set off from the text to bring attention to something.
139
140It uses pandoc’s [fenced `div`s syntax](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/fenced_divs.md):
141
142```markdown
143::: {.warning}
144This is a warning
145:::
146```
147
148The following are supported:
149
150- `caution`
151- `important`
152- `note`
153- `tip`
154- `warning`
155- `example`
156
157Example admonitions require a title to work.
158If you don't provide one, the manual won't be built.
159
160```markdown
161::: {.example #ex-showing-an-example}
162
163# Title for this example
164
165Text for the example.
166:::
167```
168
169#### [Definition lists](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/definition_lists.md)
170
171For defining a group of terms:
172
173```markdown
174pear
175: green or yellow bulbous fruit
176
177watermelon
178: green fruit with red flesh
179```
180
181## Commit conventions
182
183- Make sure you read about the [commit conventions](../CONTRIBUTING.md#commit-conventions) common to Nixpkgs as a whole.
184
185- If creating a commit purely for documentation changes, format the commit message in the following way:
186
187 ```
188 doc: (documentation summary)
189
190 (Motivation for change, relevant links, additional information.)
191 ```
192
193 Examples:
194
195 * doc: update the kernel config documentation to use `nix-shell`
196 * doc: add information about `nix-update-script`
197
198 Closes #216321.
199
200- If the commit contains more than just documentation changes, follow the commit message format relevant for the rest of the changes.
201
202## Documentation conventions
203
204In an effort to keep the Nixpkgs manual in a consistent style, please follow the conventions below, unless they prevent you from properly documenting something.
205In that case, please open an issue about the particular documentation convention and tag it with a "needs: documentation" label.
206When needed, each convention explains why it exists, so you can make a decision whether to follow it or not based on your particular case.
207Note that these conventions are about the **structure** of the manual (and its source files), not about the content that goes in it.
208You, as the writer of documentation, are still in charge of its content.
209
210### One sentence per line
211
212Put each sentence in its own line.
213This makes reviews and suggestions much easier, since GitHub's review system is based on lines.
214It also helps identifying long sentences at a glance.
215
216### Writing Function Documentation
217
218Function documentation is *reference documentation*, for which
219[diataxis Reference documentation](https://diataxis.fr/reference/) (8 minutes) is **mandatory reading**.
220
221On top of the diataxis framework, which provides a balanced perspective on what reference documentation should contain, we apply a specific style rule to function documentation:
222the first sentence is in present tense, active voice, and the subject is omitted, referring implicitly to the name of the function.
223For example:
224
225```nix
226/**
227 Subtracts value `b` from value `a`.
228
229 Returns the difference as a number.
230*/
231subtractValues # ...elided code
232```
233
234Renders as:
235
236```md
237## `subtractValues`
238
239Subtracts value `b` from value `a`.
240
241Returns the difference as a number.
242```
243
244### Callouts and examples
245
246Use the [admonition syntax](#admonitions) for callouts and examples.
247
248### Provide self-contained examples
249
250Provide at least one example per function, and make examples self-contained.
251This is easier to understand for beginners.
252It also helps with testing that it actually works – especially once we introduce automation.
253
254Example code should be such that it can be passed to `pkgs.callPackage`.
255Instead of something like:
256
257```nix
258pkgs.dockerTools.buildLayeredImage {
259 name = "hello";
260 contents = [ pkgs.hello ];
261}
262```
263
264Write something like:
265
266```nix
267{ dockerTools, hello }:
268dockerTools.buildLayeredImage {
269 name = "hello";
270 contents = [ hello ];
271}
272```
273
274### REPLs
275
276When showing inputs/outputs of any [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop), such as a shell or the Nix REPL, use a format as you'd see in the REPL, while trying to visually separate inputs from outputs.
277This means that for a shell, you should use a format like the following:
278```shell
279$ nix-build -A hello '<nixpkgs>' \
280 --option require-sigs false \
281 --option trusted-substituters file:///tmp/hello-cache \
282 --option substituters file:///tmp/hello-cache
283/nix/store/zhl06z4lrfrkw5rp0hnjjfrgsclzvxpm-hello-2.12.1
284```
285Note how the input is preceded by `$` on the first line and indented on subsequent lines, and how the output is provided as you'd see on the shell.
286
287For the Nix REPL, you should use a format like the following:
288```shell
289nix-repl> builtins.attrNames { a = 1; b = 2; }
290[ "a" "b" ]
291```
292Note how the input is preceded by `nix-repl>` and the output is provided as you'd see on the Nix REPL.
293
294### Headings for inputs, outputs and examples
295
296When documenting functions or anything that has inputs/outputs and example usage, use nested headings to clearly separate inputs, outputs, and examples.
297Keep examples as the last nested heading, and link to the examples wherever applicable in the documentation.
298
299The purpose of this convention is to provide a familiar structure for navigating the manual, so any reader can expect to find content related to inputs in an "inputs" heading, examples in an "examples" heading, and so on.
300An example:
301```
302## buildImage
303
304Some explanation about the function here.
305Describe a particular scenario, and point to [](#ex-dockerTools-buildImage), which is an example demonstrating it.
306
307### Inputs
308
309Documentation for the inputs of `buildImage`.
310Perhaps even point to [](#ex-dockerTools-buildImage) again when talking about something specifically linked to it.
311
312### Passthru outputs
313
314Documentation for any passthru outputs of `buildImage`.
315
316### Examples
317
318Note that this is the last nested heading in the `buildImage` section.
319
320:::{.example #ex-dockerTools-buildImage}
321
322# Using `buildImage`
323
324Example of how to use `buildImage` goes here.
325
326:::
327```
328
329### Function arguments
330
331Use [definition lists](#definition-lists) to document function arguments, and the attributes of such arguments as well as their [types](https://nixos.org/manual/nix/stable/language/values).
332For example:
333
334```markdown
335# pkgs.coolFunction {#pkgs.coolFunction}
336
337`pkgs.coolFunction` *`name`* *`config`*
338
339Description of what `callPackage` does.
340
341
342## Inputs {#pkgs-coolFunction-inputs}
343
344If something's special about `coolFunction`'s general argument handling, you can say so here.
345Otherwise, just describe the single argument or start the arguments' definition list without introduction.
346
347*`name`* (String)
348
349: The name of the resulting image.
350
351*`config`* (Attribute set)
352
353: Introduce the parameter. Maybe you have a test to make sure `{ }` is a sensible default; then you can say: these attributes are optional; `{ }` is a valid argument.
354
355 `outputHash` (String; _optional_)
356
357 : A brief explanation including when and when not to pass this attribute.
358
359 : _Default:_ the output path's hash.
360```
361
362Checklist:
363- Start with a synopsis, to show the order of positional arguments.
364- Metavariables are in emphasized code spans: ``` *`arg1`* ```.
365 Metavariables are placeholders where users may write arbitrary expressions.
366 This includes positional arguments.
367- Attribute names are regular code spans: ``` `attr1` ```.
368 These identifiers can _not_ be picked freely by users, so they are _not_ metavariables.
369- _optional_ attributes have a _`Default:`_ if it's easily described as a value.
370- _optional_ attributes have a _`Default behavior:`_ if it's not easily described using a value.
371- Nix types aren't in code spans, because they are not code
372- Nix types are capitalized, to distinguish them from the camelCase Module System types, which _are_ code and behave like functions.
373
374#### Examples
375
376To define a referenceable figure use the following fencing:
377
378```markdown
379:::{.example #an-attribute-set-example}
380# An attribute set example
381
382You can add text before
383
384 ```nix
385 { a = 1; b = 2;}
386 ```
387
388and after code fencing
389:::
390```
391
392Defining examples through the `example` fencing class adds them to a "List of Examples" section after the Table of Contents.
393Though this is not shown in the rendered documentation on nixos.org.
394
395#### Figures
396
397To define a referenceable figure use the following fencing:
398
399```markdown
400::: {.figure #nixos-logo}
401# NixOS Logo
402
403:::
404```
405
406Defining figures through the `figure` fencing class adds them to a `List of Figures` after the `Table of Contents`.
407Though this is not shown in the rendered documentation on nixos.org.
408
409#### Footnotes
410
411To add a foonote explanation, use the following syntax:
412
413```markdown
414Sometimes it's better to add context [^context] in a footnote.
415
416[^context]: This explanation will be rendered at the end of the chapter.
417```
418
419#### Inline comments
420
421Inline comments are supported with following syntax:
422
423```markdown
424<!-- This is an inline comment -->
425```
426
427The comments will not be rendered in the rendered HTML.
428
429#### Link reference definitions
430
431Links can reference a label, for example, to make the link target reusable:
432
433```markdown
434::: {.note}
435Reference links can also be used to [shorten URLs][url-id] and keep the markdown readable.
436:::
437
438[url-id]: https://github.com/NixOS/nixpkgs/blob/19d4f7dc485f74109bd66ef74231285ff797a823/doc/README.md
439```
440
441This syntax is taken from [CommonMark](https://spec.commonmark.org/0.30/#link-reference-definitions).
442
443#### Typographic replacements
444
445Typographic replacements are enabled.
446Check the [list of possible replacement patterns check](https://github.com/executablebooks/markdown-it-py/blob/3613e8016ecafe21709471ee0032a90a4157c2d1/markdown_it/rules_core/replacements.py#L1-L15).
447
448## Getting help
449
450If you need documentation-specific help or reviews, ping [@NixOS/documentation-team](https://github.com/orgs/nixos/teams/documentation-team) on your pull request.