pyrox.dev
1# Contributing to the Nixpkgs reference manual
2
3This directory houses the sources files for the Nixpkgs reference manual.
4
5Going forward, it should only contain [reference](https://nix.dev/contributing/documentation/diataxis#reference) documentation.
6For tutorials, guides and explanations, contribute to <https://nix.dev/> instead.
7
8For documentation only relevant for contributors, use Markdown files and code comments in the source code.
9
10Rendered documentation:
11- [Unstable (from master)](https://nixos.org/manual/nixpkgs/unstable/)
12- [Stable (from latest release)](https://nixos.org/manual/nixpkgs/stable/)
13
14The rendering tool is [nixos-render-docs](../pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs), sometimes abbreviated `nrd`.
15
16## Contributing to this documentation
17
18You can quickly check your edits with `nix-build`:
19
20```ShellSession
21$ cd /path/to/nixpkgs
22$ nix-build doc
23```
24
25If the build succeeds, the manual will be in `./result/share/doc/nixpkgs/manual.html`.
26
27### devmode
28
29The shell in the manual source directory makes available a command, `devmode`.
30It is a daemon, that:
311. watches the manual's source for changes and when they occur — rebuilds
322. HTTP serves the manual, injecting a script that triggers reload on changes
333. opens the manual in the default browser
34
35## Syntax
36
37As per [RFC 0072](https://github.com/NixOS/rfcs/pull/72), all new documentation content should be written in [CommonMark](https://commonmark.org/) Markdown dialect.
38
39Additional syntax extensions are available, all of which can be used in NixOS option documentation. The following extensions are currently used:
40
41#### Tables
42
43Tables, using the [GitHub-flavored Markdown syntax](https://github.github.com/gfm/#tables-extension-).
44
45#### Anchors
46
47Explicitly 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).
48
49It uses the widely compatible [header attributes](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/attributes.md) syntax:
50
51```markdown
52## Syntax {#sec-contributing-markup}
53```
54
55> [!Note]
56> NixOS option documentation does not support headings in general.
57
58#### Inline Anchors
59
60Allow linking arbitrary place in the text (e.g. individual list items, sentences…).
61
62They 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):
63
64```markdown
65- []{#ssec-gnome-hooks-glib} `glib` setup hook will populate `GSETTINGS_SCHEMAS_PATH` and then `wrapGApps*` hook will prepend it to `XDG_DATA_DIRS`.
66```
67
68#### Automatic links
69
70If you **omit a link text** for a link pointing to a section, the text will be substituted automatically. For example `[](#chap-contributing)`.
71
72This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing).
73
74
75#### HTML
76
77Inlining 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.
78
79#### Roles
80
81If 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).
82
83A few markups for other kinds of literals are also available:
84
85- `` {command}`rm -rfi` ``
86- `` {env}`XDG_DATA_DIRS` ``
87- `` {file}`/etc/passwd` ``
88- `` {option}`networking.useDHCP` ``
89- `` {var}`/etc/passwd` ``
90
91These literal kinds are used mostly in NixOS option documentation.
92
93This 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.
94
95#### Admonitions
96
97Set off from the text to bring attention to something.
98
99It uses pandoc’s [fenced `div`s syntax](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/fenced_divs.md):
100
101```markdown
102::: {.warning}
103This is a warning
104:::
105```
106
107The following are supported:
108
109- `caution`
110- `important`
111- `note`
112- `tip`
113- `warning`
114- `example`
115
116Example admonitions require a title to work.
117If you don't provide one, the manual won't be built.
118
119```markdown
120::: {.example #ex-showing-an-example}
121
122# Title for this example
123
124Text for the example.
125:::
126```
127
128#### [Definition lists](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/definition_lists.md)
129
130For defining a group of terms:
131
132```markdown
133pear
134: green or yellow bulbous fruit
135
136watermelon
137: green fruit with red flesh
138```
139
140## Commit conventions
141
142- Make sure you read about the [commit conventions](../CONTRIBUTING.md#commit-conventions) common to Nixpkgs as a whole.
143
144- If creating a commit purely for documentation changes, format the commit message in the following way:
145
146 ```
147 doc: (documentation summary)
148
149 (Motivation for change, relevant links, additional information.)
150 ```
151
152 Examples:
153
154 * doc: update the kernel config documentation to use `nix-shell`
155 * doc: add information about `nix-update-script`
156
157 Closes #216321.
158
159- If the commit contains more than just documentation changes, follow the commit message format relevant for the rest of the changes.
160
161## Documentation conventions
162
163In an effort to keep the Nixpkgs manual in a consistent style, please follow the conventions below, unless they prevent you from properly documenting something.
164In that case, please open an issue about the particular documentation convention and tag it with a "needs: documentation" label.
165When needed, each convention explain why it exists, so you can make a decision whether to follow it or not based on your particular case.
166Note that these conventions are about the **structure** of the manual (and its source files), not about the content that goes in it.
167You, as the writer of documentation, are still in charge of its content.
168
169- Put each sentence in its own line.
170 This makes reviews and suggestions much easier, since GitHub's review system is based on lines.
171 It also helps identifying long sentences at a glance.
172
173- Use the [admonition syntax](#admonitions) for callouts and examples.
174
175- Provide at least one example per function, and make examples self-contained.
176 This is easier to understand for beginners.
177 It also helps with testing that it actually works – especially once we introduce automation.
178
179 Example code should be such that it can be passed to `pkgs.callPackage`.
180 Instead of something like:
181
182 ```nix
183 pkgs.dockerTools.buildLayeredImage {
184 name = "hello";
185 contents = [ pkgs.hello ];
186 }
187 ```
188
189 Write something like:
190
191 ```nix
192 { dockerTools, hello }:
193 dockerTools.buildLayeredImage {
194 name = "hello";
195 contents = [ hello ];
196 }
197 ```
198
199- When 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.
200 This means that for a shell, you should use a format like the following:
201 ```shell
202 $ nix-build -A hello '<nixpkgs>' \
203 --option require-sigs false \
204 --option trusted-substituters file:///tmp/hello-cache \
205 --option substituters file:///tmp/hello-cache
206 /nix/store/zhl06z4lrfrkw5rp0hnjjfrgsclzvxpm-hello-2.12.1
207 ```
208 Note 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.
209
210 For the Nix REPL, you should use a format like the following:
211 ```shell
212 nix-repl> builtins.attrNames { a = 1; b = 2; }
213 [ "a" "b" ]
214 ```
215 Note how the input is preceded by `nix-repl>` and the output is provided as you'd see on the Nix REPL.
216
217- When documenting functions or anything that has inputs/outputs and example usage, use nested headings to clearly separate inputs, outputs, and examples.
218 Keep examples as the last nested heading, and link to the examples wherever applicable in the documentation.
219
220 The 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.
221 An example:
222 ```
223 ## buildImage
224
225 Some explanation about the function here.
226 Describe a particular scenario, and point to [](#ex-dockerTools-buildImage), which is an example demonstrating it.
227
228 ### Inputs
229
230 Documentation for the inputs of `buildImage`.
231 Perhaps even point to [](#ex-dockerTools-buildImage) again when talking about something specifically linked to it.
232
233 ### Passthru outputs
234
235 Documentation for any passthru outputs of `buildImage`.
236
237 ### Examples
238
239 Note that this is the last nested heading in the `buildImage` section.
240
241 :::{.example #ex-dockerTools-buildImage}
242
243 # Using `buildImage`
244
245 Example of how to use `buildImage` goes here.
246
247 :::
248 ```
249
250- Use [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).
251 For example:
252
253 ```markdown
254 # pkgs.coolFunction
255
256 Description of what `coolFunction` does.
257
258 ## Inputs
259
260 `coolFunction` expects a single argument which should be an attribute set, with the following possible attributes:
261
262 `name` (String)
263
264 : The name of the resulting image.
265
266 `tag` (String; _optional_)
267
268 : Tag of the generated image.
269
270 _Default:_ the output path's hash.
271 ```
272
273#### Examples
274
275To define a referenceable figure use the following fencing:
276
277```markdown
278:::{.example #an-attribute-set-example}
279# An attribute set example
280
281You can add text before
282
283 ```nix
284 { a = 1; b = 2;}
285 ```
286
287and after code fencing
288:::
289```
290
291Defining examples through the `example` fencing class adds them to a "List of Examples" section after the Table of Contents.
292Though this is not shown in the rendered documentation on nixos.org.
293
294#### Figures
295
296To define a referencable figure use the following fencing:
297
298```markdown
299::: {.figure #nixos-logo}
300# NixOS Logo
301
302:::
303```
304
305Defining figures through the `figure` fencing class adds them to a `List of Figures` after the `Table of Contents`.
306Though this is not shown in the rendered documentation on nixos.org.
307
308#### Footnotes
309
310To add a foonote explanation, use the following syntax:
311
312```markdown
313Sometimes it's better to add context [^context] in a footnote.
314
315[^context]: This explanation will be rendered at the end of the chapter.
316```
317
318#### Inline comments
319
320Inline comments are supported with following syntax:
321
322```markdown
323<!-- This is an inline comment -->
324```
325
326The comments will not be rendered in the rendered HTML.
327
328#### Link reference definitions
329
330Links can reference a label, for example, to make the link target reusable:
331
332```markdown
333::: {.note}
334Reference links can also be used to [shorten URLs][url-id] and keep the markdown readable.
335:::
336
337[url-id]: https://github.com/NixOS/nixpkgs/blob/19d4f7dc485f74109bd66ef74231285ff797a823/doc/README.md
338```
339
340This syntax is taken from [CommonMark](https://spec.commonmark.org/0.30/#link-reference-definitions).
341
342#### Typographic replacements
343
344Typographic 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).
345
346## Getting help
347
348If you need documentation-specific help or reviews, ping [@NixOS/documentation-team](https://github.com/orgs/nixos/teams/documentation-team) on your pull request.