commit a63b9c15c9d81cebb9cedc0c7fe767e3ce9589ae · pyrox.dev/nixpkgs

+78

doc/README.md

···

       71
        
       

     

       72
        
       This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing).

     

       73
        
       

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       74
        
       #### Roles

     

       75
        
       

     

       76
        
       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).

     
···

       264
        
       

     

       265
        
           _Default:_ the output path's hash.

     

       266
        
         ```

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       267
        
       

     

       268
        
       ## Getting help

     

       269

···

       71
        
       

     

       72
        
       This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing).

     

       73
        
       

     

       74
       +
       

     

       75
       +
       #### HTML

     

       76
       +
       

     

       77
       +
       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.

     

       78
       +
       

     

       79
        
       #### Roles

     

       80
        
       

     

       81
        
       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).

     
···

       269
        
       

     

       270
        
           _Default:_ the output path's hash.

     

       271
        
         ```

     

       272
       +
       

     

       273
       +
       #### Examples

     

       274
       +
       

     

       275
       +
       To define a referenceable figure use the following fencing:

     

       276
       +
       

     

       277
       +
       ```markdown

     

       278
       +
       :::{.example #an-attribute-set-example}

     

       279
       +
       # An attribute set example

     

       280
       +
       

     

       281
       +
       You can add text before

     

       282
       +
       

     

       283
       +
           ```nix

     

       284
       +
           { a = 1; b = 2;}

     

       285
       +
           ```

     

       286
       +
       

     

       287
       +
       and after code fencing

     

       288
       +
       :::

     

       289
       +
       ```

     

       290
       +
       

     

       291
       +
       Defining examples through the `example` fencing class adds them to a "List of Examples" section after the Table of Contents.

     

       292
       +
       Though this is not shown in the rendered documentation on nixos.org.

     

       293
       +
       

     

       294
       +
       #### Figures

     

       295
       +
       

     

       296
       +
       To define a referencable figure use the following fencing:

     

       297
       +
       

     

       298
       +
       ```markdown

     

       299
       +
       ::: {.figure #nixos-logo}

     

       300
       +
       # NixOS Logo

     

       301
       +
       ![NixOS logo](./nixos_logo.png)

     

       302
       +
       :::

     

       303
       +
       ```

     

       304
       +
       

     

       305
       +
       Defining figures through the `figure` fencing class adds them to a `List  of Figures` after the `Table of Contents`.

     

       306
       +
       Though this is not shown in the rendered documentation on nixos.org.

     

       307
       +
       

     

       308
       +
       #### Footnotes

     

       309
       +
       

     

       310
       +
       To add a foonote explanation, use the following syntax:

     

       311
       +
       

     

       312
       +
       ```markdown

     

       313
       +
       Sometimes 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
       +
       

     

       320
       +
       Inline comments are supported with following syntax:

     

       321
       +
       

     

       322
       +
       ```markdown

     

       323
       +
       <!-- This is an inline comment -->

     

       324
       +
       ```

     

       325
       +
       

     

       326
       +
       The comments will not be rendered in the rendered HTML.

     

       327
       +
       

     

       328
       +
       #### Link reference definitions

     

       329
       +
       

     

       330
       +
       Links can reference a label, for example, to make the link target reusable:

     

       331
       +
       

     

       332
       +
       ```markdown

     

       333
       +
       ::: {.note}

     

       334
       +
       Reference 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
       +
       

     

       340
       +
       This syntax is taken from [CommonMark](https://spec.commonmark.org/0.30/#link-reference-definitions).

     

       341
       +
       

     

       342
       +
       #### Typographic replacements

     

       343
       +
       

     

       344
       +
       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).

     

       345
        
       

     

       346
        
       ## Getting help

     

       347

+1 -1

nixos/doc/manual/contributing-to-this-manual.chapter.md

···

       1
        
       # Contributing to this manual {#chap-contributing}

     

       2
        
       

     

       3
       -
       The [DocBook] and CommonMark sources of the NixOS manual are in the [nixos/doc/manual](https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual) subdirectory of the [Nixpkgs](https://github.com/NixOS/nixpkgs) repository.

     

       4
        
       This manual uses the [Nixpkgs manual syntax](https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup).

     

       5
        
       

     

       6
        
       You can quickly check your edits with the following:

···

       1
        
       # Contributing to this manual {#chap-contributing}

     

       2
        
       

     

       3
       +
       The sources of the NixOS manual are in the [nixos/doc/manual](https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual) subdirectory of the [Nixpkgs](https://github.com/NixOS/nixpkgs) repository.

     

       4
        
       This manual uses the [Nixpkgs manual syntax](https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup).

     

       5
        
       

     

       6
        
       You can quickly check your edits with the following:

+1 -63

nixos/doc/manual/development/writing-documentation.chapter.md

···

       7
        
       

     

       8
        
       ## Building the Manual {#sec-writing-docs-building-the-manual}

     

       9
        
       

     

       10
       -
       The DocBook sources of the [](#book-nixos-manual) are in the

     

       11
        
       [`nixos/doc/manual`](https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual)

     

       12
        
       subdirectory of the Nixpkgs repository.

     

       13
        
       

     
···

       29
        
       When this command successfully finishes, it will tell you where the

     

       30
        
       manual got generated. The HTML will be accessible through the `result`

     

       31
        
       symlink at `./result/share/doc/nixos/index.html`.

     

       32
       -
       

     

       33
       -
       ## Editing DocBook XML {#sec-writing-docs-editing-docbook-xml}

     

       34
       -
       

     

       35
       -
       For general information on how to write in DocBook, see [DocBook 5: The

     

       36
       -
       Definitive Guide](https://tdg.docbook.org/tdg/5.1/).

     

       37
       -
       

     

       38
       -
       Emacs nXML Mode is very helpful for editing DocBook XML because it

     

       39
       -
       validates the document as you write, and precisely locates errors. To

     

       40
       -
       use it, see [](#sec-emacs-docbook-xml).

     

       41
       -
       

     

       42
       -
       [Pandoc](https://pandoc.org/) can generate DocBook XML from a multitude of

     

       43
       -
       formats, which makes a good starting point. Here is an example of Pandoc

     

       44
       -
       invocation to convert GitHub-Flavoured MarkDown to DocBook 5 XML:

     

       45
       -
       

     

       46
       -
       ```ShellSession

     

       47
       -
       pandoc -f markdown_github -t docbook5 docs.md -o my-section.md

     

       48
       -
       ```

     

       49
       -
       

     

       50
       -
       Pandoc can also quickly convert a single `section.xml` to HTML, which is

     

       51
       -
       helpful when drafting.

     

       52
       -
       

     

       53
       -
       Sometimes writing valid DocBook is too difficult. In this case,

     

       54
       -
       submit your documentation updates in a [GitHub

     

       55
       -
       Issue](https://github.com/NixOS/nixpkgs/issues/new) and someone will

     

       56
       -
       handle the conversion to XML for you.

     

       57
       -
       

     

       58
       -
       ## Creating a Topic {#sec-writing-docs-creating-a-topic}

     

       59
       -
       

     

       60
       -
       You can use an existing topic as a basis for the new topic or create a

     

       61
       -
       topic from scratch.

     

       62
       -
       

     

       63
       -
       Keep the following guidelines in mind when you create and add a topic:

     

       64
       -
       

     

       65
       -
       -   The NixOS [`book`](https://tdg.docbook.org/tdg/5.0/book.html)

     

       66
       -
           element is in `nixos/doc/manual/manual.xml`. It includes several

     

       67
       -
           [`parts`](https://tdg.docbook.org/tdg/5.0/book.html) which are in

     

       68
       -
           subdirectories.

     

       69
       -
       

     

       70
       -
       -   Store the topic file in the same directory as the `part` to which it

     

       71
       -
           belongs. If your topic is about configuring a NixOS module, then the

     

       72
       -
           XML file can be stored alongside the module definition `nix` file.

     

       73
       -
       

     

       74
       -
       -   If you include multiple words in the file name, separate the words

     

       75
       -
           with a dash. For example: `ipv6-config.xml`.

     

       76
       -
       

     

       77
       -
       -   Make sure that the `xml:id` value is unique. You can use abbreviations

     

       78
       -
           if the ID is too long. For example: `nixos-config`.

     

       79
       -
       

     

       80
       -
       -   Determine whether your topic is a chapter or a section. If you are

     

       81
       -
           unsure, open an existing topic file and check whether the main

     

       82
       -
           element is chapter or section.

     

       83
       -
       

     

       84
       -
       ## Adding a Topic to the Book {#sec-writing-docs-adding-a-topic}

     

       85
       -
       

     

       86
       -
       Open the parent CommonMark file and add a line to the list of

     

       87
       -
       chapters with the file name of the topic that you created. If you

     

       88
       -
       created a `section`, you add the file to the `chapter` file. If you created

     

       89
       -
       a `chapter`, you add the file to the `part` file.

     

       90
       -
       

     

       91
       -
       If the topic is about configuring a NixOS module, it can be

     

       92
       -
       automatically included in the manual by using the `meta.doc` attribute.

     

       93
       -
       See [](#sec-meta-attributes) for an explanation.

···

       7
        
       

     

       8
        
       ## Building the Manual {#sec-writing-docs-building-the-manual}

     

       9
        
       

     

       10
       +
       The sources of the [](#book-nixos-manual) are in the

     

       11
        
       [`nixos/doc/manual`](https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual)

     

       12
        
       subdirectory of the Nixpkgs repository.

     

       13
        
       

     
···

       29
        
       When this command successfully finishes, it will tell you where the

     

       30
        
       manual got generated. The HTML will be accessible through the `result`

     

       31
        
       symlink at `./result/share/doc/nixos/index.html`.

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0