diff options
Diffstat (limited to 'nixpkgs/doc/README.md')
| -rw-r--r-- | nixpkgs/doc/README.md | 145 |
1 files changed, 140 insertions, 5 deletions
diff --git a/nixpkgs/doc/README.md b/nixpkgs/doc/README.md index 4ed9c47aee95..1e9305d040ba 100644 --- a/nixpkgs/doc/README.md +++ b/nixpkgs/doc/README.md @@ -71,6 +71,11 @@ If you **omit a link text** for a link pointing to a section, the text will be s This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing). + +#### HTML + +Inlining 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. + #### Roles If 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). @@ -157,6 +162,9 @@ watermelon In an effort to keep the Nixpkgs manual in a consistent style, please follow the conventions below, unless they prevent you from properly documenting something. In that case, please open an issue about the particular documentation convention and tag it with a "needs: documentation" label. +When needed, each convention explain why it exists, so you can make a decision whether to follow it or not based on your particular case. +Note that these conventions are about the **structure** of the manual (and its source files), not about the content that goes in it. +You, as the writer of documentation, are still in charge of its content. - Put each sentence in its own line. This makes reviews and suggestions much easier, since GitHub's review system is based on lines. @@ -188,26 +196,153 @@ In that case, please open an issue about the particular documentation convention } ``` -- Use [definition lists](#definition-lists) to document function arguments, and the attributes of such arguments. For example: +- 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. + This means that for a shell, you should use a format like the following: + ```shell + $ nix-build -A hello '<nixpkgs>' \ + --option require-sigs false \ + --option trusted-substituters file:///tmp/hello-cache \ + --option substituters file:///tmp/hello-cache + /nix/store/zhl06z4lrfrkw5rp0hnjjfrgsclzvxpm-hello-2.12.1 + ``` + 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. + + For the Nix REPL, you should use a format like the following: + ```shell + nix-repl> builtins.attrNames { a = 1; b = 2; } + [ "a" "b" ] + ``` + Note how the input is preceded by `nix-repl>` and the output is provided as you'd see on the Nix REPL. + +- When documenting functions or anything that has inputs/outputs and example usage, use nested headings to clearly separate inputs, outputs, and examples. + Keep examples as the last nested heading, and link to the examples wherever applicable in the documentation. + + 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. + An example: + ``` + ## buildImage + + Some explanation about the function here. + Describe a particular scenario, and point to [](#ex-dockerTools-buildImage), which is an example demonstrating it. + + ### Inputs + + Documentation for the inputs of `buildImage`. + Perhaps even point to [](#ex-dockerTools-buildImage) again when talking about something specifically linked to it. + + ### Passthru outputs + + Documentation for any passthru outputs of `buildImage`. + + ### Examples + + Note that this is the last nested heading in the `buildImage` section. + + :::{.example #ex-dockerTools-buildImage} + + # Using `buildImage` + + Example of how to use `buildImage` goes here. + + ::: + ``` + +- 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). + For example: ```markdown # pkgs.coolFunction Description of what `coolFunction` does. + + ## Inputs + `coolFunction` expects a single argument which should be an attribute set, with the following possible attributes: - `name` + `name` (String) : The name of the resulting image. - `tag` _optional_ + `tag` (String; _optional_) : Tag of the generated image. - _Default value:_ the output path's hash. - + _Default:_ the output path's hash. ``` +#### Examples + +To define a referenceable figure use the following fencing: + +```markdown +:::{.example #an-attribute-set-example} +# An attribute set example + +You can add text before + + ```nix + { a = 1; b = 2;} + ``` + +and after code fencing +::: +``` + +Defining examples through the `example` fencing class adds them to a "List of Examples" section after the Table of Contents. +Though this is not shown in the rendered documentation on nixos.org. + +#### Figures + +To define a referencable figure use the following fencing: + +```markdown +::: {.figure #nixos-logo} +# NixOS Logo + +::: +``` + +Defining figures through the `figure` fencing class adds them to a `List of Figures` after the `Table of Contents`. +Though this is not shown in the rendered documentation on nixos.org. + +#### Footnotes + +To add a foonote explanation, use the following syntax: + +```markdown +Sometimes it's better to add context [^context] in a footnote. + +[^context]: This explanation will be rendered at the end of the chapter. +``` + +#### Inline comments + +Inline comments are supported with following syntax: + +```markdown +<!-- This is an inline comment --> +``` + +The comments will not be rendered in the rendered HTML. + +#### Link reference definitions + +Links can reference a label, for example, to make the link target reusable: + +```markdown +::: {.note} +Reference links can also be used to [shorten URLs][url-id] and keep the markdown readable. +::: + +[url-id]: https://github.com/NixOS/nixpkgs/blob/19d4f7dc485f74109bd66ef74231285ff797a823/doc/README.md +``` + +This syntax is taken from [CommonMark](https://spec.commonmark.org/0.30/#link-reference-definitions). + +#### Typographic replacements + +Typographic 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). + ## Getting help If you need documentation-specific help or reviews, ping [@NixOS/documentation-reviewers](https://github.com/orgs/nixos/teams/documentation-reviewers) on your pull request. |