commit a63b9c15c9d81cebb9cedc0c7fe767e3ce9589ae · pyrox.dev/nixpkgs

+78

doc/README.md

···

       71
       71
        
       

     

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

     

       73
       73
        
       

     

       74
       74
       +
       

     

       75
       75
       +
       #### HTML

     

       76
       76
       +
       

     

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

     

       74
       79
        
       #### Roles

     

       75
       80
        
       

     

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

     
···

       264
       269
        
       

     

       265
       270
        
           _Default:_ the output path's hash.

     

       266
       271
        
         ```

     

       272
       272
       +
       

     

       273
       273
       +
       #### Examples

     

       274
       274
       +
       

     

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

     

       276
       276
       +
       

     

       277
       277
       +
       ```markdown

     

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

     

       279
       279
       +
       # An attribute set example

     

       280
       280
       +
       

     

       281
       281
       +
       You can add text before

     

       282
       282
       +
       

     

       283
       283
       +
           ```nix

     

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

     

       285
       285
       +
           ```

     

       286
       286
       +
       

     

       287
       287
       +
       and after code fencing

     

       288
       288
       +
       :::

     

       289
       289
       +
       ```

     

       290
       290
       +
       

     

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

     

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

     

       293
       293
       +
       

     

       294
       294
       +
       #### Figures

     

       295
       295
       +
       

     

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

     

       297
       297
       +
       

     

       298
       298
       +
       ```markdown

     

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

     

       300
       300
       +
       # NixOS Logo

     

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

     

       302
       302
       +
       :::

     

       303
       303
       +
       ```

     

       304
       304
       +
       

     

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

     

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

     

       307
       307
       +
       

     

       308
       308
       +
       #### Footnotes

     

       309
       309
       +
       

     

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

     

       311
       311
       +
       

     

       312
       312
       +
       ```markdown

     

       313
       313
       +
       Sometimes it's better to add context [^context] in a footnote.

     

       314
       314
       +
       

     

       315
       315
       +
       [^context]: This explanation will be rendered at the end of the chapter.

     

       316
       316
       +
       ```

     

       317
       317
       +
       

     

       318
       318
       +
       #### Inline comments

     

       319
       319
       +
       

     

       320
       320
       +
       Inline comments are supported with following syntax:

     

       321
       321
       +
       

     

       322
       322
       +
       ```markdown

     

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

     

       324
       324
       +
       ```

     

       325
       325
       +
       

     

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

     

       327
       327
       +
       

     

       328
       328
       +
       #### Link reference definitions

     

       329
       329
       +
       

     

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

     

       331
       331
       +
       

     

       332
       332
       +
       ```markdown

     

       333
       333
       +
       ::: {.note}

     

       334
       334
       +
       Reference links can also be used to [shorten URLs][url-id] and keep the markdown readable.

     

       335
       335
       +
       :::

     

       336
       336
       +
       

     

       337
       337
       +
       [url-id]: https://github.com/NixOS/nixpkgs/blob/19d4f7dc485f74109bd66ef74231285ff797a823/doc/README.md

     

       338
       338
       +
       ```

     

       339
       339
       +
       

     

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

     

       341
       341
       +
       

     

       342
       342
       +
       #### Typographic replacements

     

       343
       343
       +
       

     

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

     

       267
       345
        
       

     

       268
       346
        
       ## Getting help

     

       269
       347

+1 -1

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

···

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

     

       2
       2
        
       

     

       3
       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.

     

       3
       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
       4
        
       This manual uses the [Nixpkgs manual syntax](https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup).

     

       5
       5
        
       

     

       6
       6
        
       You can quickly check your edits with the following:

+1 -63

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

···

       7
       7
        
       

     

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

     

       9
       9
        
       

     

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

     

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

     

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

     

       12
       12
        
       subdirectory of the Nixpkgs repository.

     

       13
       13
        
       

     
···

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

     

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

     

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

     

       32
       32
       -
       

     

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

     

       34
       34
       -
       

     

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

     

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

     

       37
       37
       -
       

     

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

     

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

     

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

     

       41
       41
       -
       

     

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

     

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

     

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

     

       45
       45
       -
       

     

       46
       46
       -
       ```ShellSession

     

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

     

       48
       48
       -
       ```

     

       49
       49
       -
       

     

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

     

       51
       51
       -
       helpful when drafting.

     

       52
       52
       -
       

     

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

     

       54
       54
       -
       submit your documentation updates in a [GitHub

     

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

     

       56
       56
       -
       handle the conversion to XML for you.

     

       57
       57
       -
       

     

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

     

       59
       59
       -
       

     

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

     

       61
       61
       -
       topic from scratch.

     

       62
       62
       -
       

     

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

     

       64
       64
       -
       

     

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

     

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

     

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

     

       68
       68
       -
           subdirectories.

     

       69
       69
       -
       

     

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

     

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

     

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

     

       73
       73
       -
       

     

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

     

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

     

       76
       76
       -
       

     

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

     

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

     

       79
       79
       -
       

     

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

     

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

     

       82
       82
       -
           element is chapter or section.

     

       83
       83
       -
       

     

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

     

       85
       85
       -
       

     

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

     

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

     

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

     

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

     

       90
       90
       -
       

     

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

     

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

     

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