pyrox.dev
1# Contributing to the Nixpkgs reference manual
2
3This directory houses the sources 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### devmode
38
39The shell in the manual source directory makes available a command, `devmode`.
40It is a daemon, that:
411. watches the manual's source for changes and when they occur — rebuilds
422. HTTP serves the manual, injecting a script that triggers reload on changes
433. opens the manual in the default browser
44
45### Testing redirects
46
47Once 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.
48
49Note that if you already loaded the page and *then* input the anchor, you will need to perform a reload. This is because browsers do not re-run client JS code when only the anchor has changed.
50
51## Syntax
52
53As per [RFC 0072](https://github.com/NixOS/rfcs/pull/72), all new documentation content should be written in [CommonMark](https://commonmark.org/) Markdown dialect.
54
55Additional syntax extensions are available, all of which can be used in NixOS option documentation. The following extensions are currently used:
56
57#### Tables
58
59Tables, using the [GitHub-flavored Markdown syntax](https://github.github.com/gfm/#tables-extension-).
60
61#### Anchors
62
63Explicitly defined **anchors** on headings, to allow linking to sections. These 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).
64
65It uses the widely compatible [header attributes](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/attributes.md) syntax:
66
67```markdown
68## Syntax {#sec-contributing-markup}
69```
70
71> [!Note]
72> NixOS option documentation does not support headings in general.
73
74#### Inline Anchors
75
76Allow linking arbitrary place in the text (e.g. individual list items, sentences…).
77
78They 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):
79
80```markdown
81- []{#ssec-gnome-hooks-glib} `glib` setup hook will populate `GSETTINGS_SCHEMAS_PATH` and then `wrapGApps*` hook will prepend it to `XDG_DATA_DIRS`.
82```
83
84#### Automatic links
85
86If you **omit a link text** for a link pointing to a section, the text will be substituted automatically. For example `[](#chap-contributing)`.
87
88This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing).
89
90
91#### HTML
92
93Inlining HTML is not allowed. Parts of the documentation gets rendered to various non-HTML formats, such as man pages in the case of NixOS manual.
94
95#### Roles
96
97If you want to link to a man page, you can use `` {manpage}`nix.conf(5)` ``. The references will turn into links when a mapping exists in [`doc/manpage-urls.json`](./manpage-urls.json).
98Please keep the `manpage-urls.json` file alphabetically sorted.
99
100A few markups for other kinds of literals are also available:
101
102- `` {command}`rm -rfi` ``
103- `` {env}`XDG_DATA_DIRS` ``
104- `` {file}`/etc/passwd` ``
105- `` {option}`networking.useDHCP` ``
106- `` {var}`/etc/passwd` ``
107
108These literal kinds are used mostly in NixOS option documentation.
109
110This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point). Though, the feature originates from [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-manpage) with slightly different syntax.
111They are handled by `myst_role` defined per renderer. <!-- reverse references in code -->
112
113#### Admonitions
114
115Set off from the text to bring attention to something.
116
117It uses pandoc’s [fenced `div`s syntax](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/fenced_divs.md):
118
119```markdown
120::: {.warning}
121This is a warning
122:::
123```
124
125The following are supported:
126
127- `caution`
128- `important`
129- `note`
130- `tip`
131- `warning`
132- `example`
133
134Example admonitions require a title to work.
135If you don't provide one, the manual won't be built.
136
137```markdown
138::: {.example #ex-showing-an-example}
139
140# Title for this example
141
142Text for the example.
143:::
144```
145
146#### [Definition lists](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/definition_lists.md)
147
148For defining a group of terms:
149
150```markdown
151pear
152: green or yellow bulbous fruit
153
154watermelon
155: green fruit with red flesh
156```
157
158## Commit conventions
159
160- Make sure you read about the [commit conventions](../CONTRIBUTING.md#commit-conventions) common to Nixpkgs as a whole.
161
162- If creating a commit purely for documentation changes, format the commit message in the following way:
163
164 ```
165 doc: (documentation summary)
166
167 (Motivation for change, relevant links, additional information.)
168 ```
169
170 Examples:
171
172 * doc: update the kernel config documentation to use `nix-shell`
173 * doc: add information about `nix-update-script`
174
175 Closes #216321.
176
177- If the commit contains more than just documentation changes, follow the commit message format relevant for the rest of the changes.
178
179## Documentation conventions
180
181In an effort to keep the Nixpkgs manual in a consistent style, please follow the conventions below, unless they prevent you from properly documenting something.
182In that case, please open an issue about the particular documentation convention and tag it with a "needs: documentation" label.
183When needed, each convention explain why it exists, so you can make a decision whether to follow it or not based on your particular case.
184Note that these conventions are about the **structure** of the manual (and its source files), not about the content that goes in it.
185You, as the writer of documentation, are still in charge of its content.
186
187### One sentence per line
188
189Put each sentence in its own line.
190This makes reviews and suggestions much easier, since GitHub's review system is based on lines.
191It also helps identifying long sentences at a glance.
192
193### Callouts and examples
194
195Use the [admonition syntax](#admonitions) for callouts and examples.
196
197### Provide self-contained examples
198
199Provide at least one example per function, and make examples self-contained.
200This is easier to understand for beginners.
201It also helps with testing that it actually works – especially once we introduce automation.
202
203Example code should be such that it can be passed to `pkgs.callPackage`.
204Instead of something like:
205
206```nix
207pkgs.dockerTools.buildLayeredImage {
208 name = "hello";
209 contents = [ pkgs.hello ];
210}
211```
212
213Write something like:
214
215```nix
216{ dockerTools, hello }:
217dockerTools.buildLayeredImage {
218 name = "hello";
219 contents = [ hello ];
220}
221```
222
223### REPLs
224
225When 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.
226This means that for a shell, you should use a format like the following:
227```shell
228$ nix-build -A hello '<nixpkgs>' \
229 --option require-sigs false \
230 --option trusted-substituters file:///tmp/hello-cache \
231 --option substituters file:///tmp/hello-cache
232/nix/store/zhl06z4lrfrkw5rp0hnjjfrgsclzvxpm-hello-2.12.1
233```
234Note 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.
235
236For the Nix REPL, you should use a format like the following:
237```shell
238nix-repl> builtins.attrNames { a = 1; b = 2; }
239[ "a" "b" ]
240```
241Note how the input is preceded by `nix-repl>` and the output is provided as you'd see on the Nix REPL.
242
243### Headings for inputs, outputs and examples
244
245When documenting functions or anything that has inputs/outputs and example usage, use nested headings to clearly separate inputs, outputs, and examples.
246Keep examples as the last nested heading, and link to the examples wherever applicable in the documentation.
247
248The 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.
249An example:
250```
251## buildImage
252
253Some explanation about the function here.
254Describe a particular scenario, and point to [](#ex-dockerTools-buildImage), which is an example demonstrating it.
255
256### Inputs
257
258Documentation for the inputs of `buildImage`.
259Perhaps even point to [](#ex-dockerTools-buildImage) again when talking about something specifically linked to it.
260
261### Passthru outputs
262
263Documentation for any passthru outputs of `buildImage`.
264
265### Examples
266
267Note that this is the last nested heading in the `buildImage` section.
268
269:::{.example #ex-dockerTools-buildImage}
270
271# Using `buildImage`
272
273Example of how to use `buildImage` goes here.
274
275:::
276```
277
278### Function arguments
279
280Use [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).
281For example:
282
283```markdown
284# pkgs.coolFunction {#pkgs.coolFunction}
285
286`pkgs.coolFunction` *`name`* *`config`*
287
288Description of what `callPackage` does.
289
290
291## Inputs {#pkgs-coolFunction-inputs}
292
293If something's special about `coolFunction`'s general argument handling, you can say so here.
294Otherwise, just describe the single argument or start the arguments' definition list without introduction.
295
296*`name`* (String)
297
298: The name of the resulting image.
299
300*`config`* (Attribute set)
301
302: 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.
303
304 `outputHash` (String; _optional_)
305
306 : A brief explanation including when and when not to pass this attribute.
307
308 : _Default:_ the output path's hash.
309```
310
311Checklist:
312- Start with a synopsis, to show the order of positional arguments.
313- Metavariables are in emphasized code spans: ``` *`arg1`* ```. Metavariables are placeholders where users may write arbitrary expressions. This includes positional arguments.
314- Attribute names are regular code spans: ``` `attr1` ```. These identifiers can _not_ be picked freely by users, so they are _not_ metavariables.
315- _optional_ attributes have a _`Default:`_ if it's easily described as a value.
316- _optional_ attributes have a _`Default behavior:`_ if it's not easily described using a value.
317- Nix types aren't in code spans, because they are not code
318- Nix types are capitalized, to distinguish them from the camelCase Module System types, which _are_ code and behave like functions.
319
320#### Examples
321
322To define a referenceable figure use the following fencing:
323
324```markdown
325:::{.example #an-attribute-set-example}
326# An attribute set example
327
328You can add text before
329
330 ```nix
331 { a = 1; b = 2;}
332 ```
333
334and after code fencing
335:::
336```
337
338Defining examples through the `example` fencing class adds them to a "List of Examples" section after the Table of Contents.
339Though this is not shown in the rendered documentation on nixos.org.
340
341#### Figures
342
343To define a referenceable figure use the following fencing:
344
345```markdown
346::: {.figure #nixos-logo}
347# NixOS Logo
348
349:::
350```
351
352Defining figures through the `figure` fencing class adds them to a `List of Figures` after the `Table of Contents`.
353Though this is not shown in the rendered documentation on nixos.org.
354
355#### Footnotes
356
357To add a foonote explanation, use the following syntax:
358
359```markdown
360Sometimes it's better to add context [^context] in a footnote.
361
362[^context]: This explanation will be rendered at the end of the chapter.
363```
364
365#### Inline comments
366
367Inline comments are supported with following syntax:
368
369```markdown
370<!-- This is an inline comment -->
371```
372
373The comments will not be rendered in the rendered HTML.
374
375#### Link reference definitions
376
377Links can reference a label, for example, to make the link target reusable:
378
379```markdown
380::: {.note}
381Reference links can also be used to [shorten URLs][url-id] and keep the markdown readable.
382:::
383
384[url-id]: https://github.com/NixOS/nixpkgs/blob/19d4f7dc485f74109bd66ef74231285ff797a823/doc/README.md
385```
386
387This syntax is taken from [CommonMark](https://spec.commonmark.org/0.30/#link-reference-definitions).
388
389#### Typographic replacements
390
391Typographic replacements are enabled. Check the [list of possible replacement patterns check](https://github.com/executablebooks/markdown-it-py/blob/3613e8016ecafe21709471ee0032a90a4157c2d1/markdown_it/rules_core/replacements.py#L1-L15).
392
393## Getting help
394
395If you need documentation-specific help or reviews, ping [@NixOS/documentation-team](https://github.com/orgs/nixos/teams/documentation-team) on your pull request.