commit 74b17a515f8fb8cb59e54bf21e7be4861e239009 · pyrox.dev/nixpkgs

+116

doc/README.md

···

       9
       9
        
       If you want to contribute to the documentation, [here's how to do it](https://nixos.org/manual/nixpkgs/unstable/#chap-contributing).

     

       10
       10
        
       

     

       11
       11
        
       If you're only getting started with Nix, go to [nixos.org/learn](https://nixos.org/learn).

     

       12
       12
       +
       

     

       13
       13
       +
       ## Contributing to this documentation {#chap-contributing}

     

       14
       14
       +
       

     

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

     

       16
       16
       +
       

     

       17
       17
       +
       You can quickly check your edits with `nix-build`:

     

       18
       18
       +
       

     

       19
       19
       +
       ```ShellSession

     

       20
       20
       +
       $ cd /path/to/nixpkgs

     

       21
       21
       +
       $ nix-build doc

     

       22
       22
       +
       ```

     

       23
       23
       +
       

     

       24
       24
       +
       If the build succeeds, the manual will be in `./result/share/doc/nixpkgs/manual.html`.

     

       25
       25
       +
       

     

       26
       26
       +
       ### devmode {#sec-contributing-devmode}

     

       27
       27
       +
       

     

       28
       28
       +
       The shell in the manual source directory makes available a command, `devmode`.

     

       29
       29
       +
       It is a daemon, that:

     

       30
       30
       +
       1. watches the manual's source for changes and when they occur — rebuilds

     

       31
       31
       +
       2. HTTP serves the manual, injecting a script that triggers reload on changes

     

       32
       32
       +
       3. opens the manual in the default browser

     

       33
       33
       +
       

     

       34
       34
       +
       ### Syntax {#sec-contributing-markup}

     

       35
       35
       +
       

     

       36
       36
       +
       As per [RFC 0072](https://github.com/NixOS/rfcs/pull/72), all new documentation content should be written in [CommonMark](https://commonmark.org/) Markdown dialect.

     

       37
       37
       +
       

     

       38
       38
       +
       Additional syntax extensions are available, all of which can be used in NixOS option documentation. The following extensions are currently used:

     

       39
       39
       +
       

     

       40
       40
       +
       - []{#ssec-contributing-markup-tables}

     

       41
       41
       +
         Tables, using the [GitHub-flavored Markdown syntax](https://github.github.com/gfm/#tables-extension-).

     

       42
       42
       +
       

     

       43
       43
       +
       - []{#ssec-contributing-markup-anchors}

     

       44
       44
       +
         Explicitly 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).

     

       45
       45
       +
       

     

       46
       46
       +
         It uses the widely compatible [header attributes](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/attributes.md) syntax:

     

       47
       47
       +
       

     

       48
       48
       +
         ```markdown

     

       49
       49
       +
         ## Syntax {#sec-contributing-markup}

     

       50
       50
       +
         ```

     

       51
       51
       +
       

     

       52
       52
       +
         ::: {.note}

     

       53
       53
       +
         NixOS option documentation does not support headings in general.

     

       54
       54
       +
         :::

     

       55
       55
       +
       

     

       56
       56
       +
       - []{#ssec-contributing-markup-anchors-inline}

     

       57
       57
       +
         **Inline anchors**, which allow linking arbitrary place in the text (e.g. individual list items, sentences…).

     

       58
       58
       +
       

     

       59
       59
       +
         They 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):

     

       60
       60
       +
       

     

       61
       61
       +
         ```markdown

     

       62
       62
       +
         - []{#ssec-gnome-hooks-glib} `glib` setup hook will populate `GSETTINGS_SCHEMAS_PATH` and then `wrapGAppsHook` will prepend it to `XDG_DATA_DIRS`.

     

       63
       63
       +
         ```

     

       64
       64
       +
       

     

       65
       65
       +
       - []{#ssec-contributing-markup-automatic-links}

     

       66
       66
       +
         If you **omit a link text** for a link pointing to a section, the text will be substituted automatically. For example, `[](#chap-contributing)` will result in [](#chap-contributing).

     

       67
       67
       +
       

     

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

     

       69
       69
       +
       

     

       70
       70
       +
       - []{#ssec-contributing-markup-inline-roles}

     

       71
       71
       +
         If you want to link to a man page, you can use `` {manpage}`nix.conf(5)` ``, which will turn into {manpage}`nix.conf(5)`. The references will turn into links when a mapping exists in {file}`doc/manpage-urls.json`.

     

       72
       72
       +
       

     

       73
       73
       +
         A few markups for other kinds of literals are also available:

     

       74
       74
       +
       

     

       75
       75
       +
         - `` {command}`rm -rfi` `` turns into {command}`rm -rfi`

     

       76
       76
       +
         - `` {env}`XDG_DATA_DIRS` `` turns into {env}`XDG_DATA_DIRS`

     

       77
       77
       +
         - `` {file}`/etc/passwd` `` turns into {file}`/etc/passwd`

     

       78
       78
       +
         - `` {option}`networking.useDHCP` `` turns into {option}`networking.useDHCP`

     

       79
       79
       +
         - `` {var}`/etc/passwd` `` turns into {var}`/etc/passwd`

     

       80
       80
       +
       

     

       81
       81
       +
         These literal kinds are used mostly in NixOS option documentation.

     

       82
       82
       +
       

     

       83
       83
       +
         This 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.

     

       84
       84
       +
       

     

       85
       85
       +
       - []{#ssec-contributing-markup-admonitions}

     

       86
       86
       +
         **Admonitions**, set off from the text to bring attention to something.

     

       87
       87
       +
       

     

       88
       88
       +
         It uses pandoc’s [fenced `div`s syntax](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/fenced_divs.md):

     

       89
       89
       +
       

     

       90
       90
       +
         ```markdown

     

       91
       91
       +
         ::: {.warning}

     

       92
       92
       +
         This is a warning

     

       93
       93
       +
         :::

     

       94
       94
       +
         ```

     

       95
       95
       +
       

     

       96
       96
       +
         which renders as

     

       97
       97
       +
       

     

       98
       98
       +
         > ::: {.warning}

     

       99
       99
       +
         > This is a warning.

     

       100
       100
       +
         > :::

     

       101
       101
       +
       

     

       102
       102
       +
         The following are supported:

     

       103
       103
       +
       

     

       104
       104
       +
           - [`caution`](https://tdg.docbook.org/tdg/5.0/caution.html)

     

       105
       105
       +
           - [`important`](https://tdg.docbook.org/tdg/5.0/important.html)

     

       106
       106
       +
           - [`note`](https://tdg.docbook.org/tdg/5.0/note.html)

     

       107
       107
       +
           - [`tip`](https://tdg.docbook.org/tdg/5.0/tip.html)

     

       108
       108
       +
           - [`warning`](https://tdg.docbook.org/tdg/5.0/warning.html)

     

       109
       109
       +
       

     

       110
       110
       +
       - []{#ssec-contributing-markup-definition-lists}

     

       111
       111
       +
         [**Definition lists**](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/definition_lists.md), for defining a group of terms:

     

       112
       112
       +
       

     

       113
       113
       +
         ```markdown

     

       114
       114
       +
         pear

     

       115
       115
       +
         :   green or yellow bulbous fruit

     

       116
       116
       +
       

     

       117
       117
       +
         watermelon

     

       118
       118
       +
         :   green fruit with red flesh

     

       119
       119
       +
         ```

     

       120
       120
       +
       

     

       121
       121
       +
         which renders as

     

       122
       122
       +
       

     

       123
       123
       +
         > pear

     

       124
       124
       +
         > :   green or yellow bulbous fruit

     

       125
       125
       +
         >

     

       126
       126
       +
         > watermelon

     

       127
       127
       +
         > :   green fruit with red flesh

+3 -107

doc/contributing/contributing-to-documentation.chapter.md

···

       1
       1
        
       # Contributing to Nixpkgs documentation {#chap-contributing}

     

       2
       2
        
       

     

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

     

       4
       4
       -
       

     

       5
       5
       -
       You can quickly check your edits with `nix-build`:

     

       6
       6
       -
       

     

       7
       7
       -
       ```ShellSession

     

       8
       8
       -
       $ cd /path/to/nixpkgs

     

       9
       9
       -
       $ nix-build doc

     

       10
       10
       -
       ```

     

       11
       11
       -
       

     

       12
       12
       -
       If the build succeeds, the manual will be in `./result/share/doc/nixpkgs/manual.html`.

     

       3
       3
       +
       This section has been moved to [doc/README.md](https://github.com/NixOS/nixpkgs/blob/master/doc/README.md).

     

       13
       4
        
       

     

       14
       5
        
       ## devmode {#sec-contributing-devmode}

     

       15
       6
        
       

     

       16
       16
       -
       The shell in the manual source directory makes available a command, `devmode`.

     

       17
       17
       -
       It is a daemon, that:

     

       18
       18
       -
       1. watches the manual's source for changes and when they occur — rebuilds

     

       19
       19
       -
       2. HTTP serves the manual, injecting a script that triggers reload on changes

     

       20
       20
       -
       3. opens the manual in the default browser

     

       7
       7
       +
       This section has been moved to [doc/README.md](https://github.com/NixOS/nixpkgs/blob/master/doc/README.md).

     

       21
       8
        
       

     

       22
       9
        
       ## Syntax {#sec-contributing-markup}

     

       23
       10
        
       

     

       24
       24
       -
       As per [RFC 0072](https://github.com/NixOS/rfcs/pull/72), all new documentation content should be written in [CommonMark](https://commonmark.org/) Markdown dialect.

     

       25
       25
       -
       

     

       26
       26
       -
       Additional syntax extensions are available, all of which can be used in NixOS option documentation. The following extensions are currently used:

     

       27
       27
       -
       

     

       28
       28
       -
       - []{#ssec-contributing-markup-tables}

     

       29
       29
       -
         Tables, using the [GitHub-flavored Markdown syntax](https://github.github.com/gfm/#tables-extension-).

     

       30
       30
       -
       

     

       31
       31
       -
       - []{#ssec-contributing-markup-anchors}

     

       32
       32
       -
         Explicitly 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).

     

       33
       33
       -
       

     

       34
       34
       -
         It uses the widely compatible [header attributes](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/attributes.md) syntax:

     

       35
       35
       -
       

     

       36
       36
       -
         ```markdown

     

       37
       37
       -
         ## Syntax {#sec-contributing-markup}

     

       38
       38
       -
         ```

     

       39
       39
       -
       

     

       40
       40
       -
         ::: {.note}

     

       41
       41
       -
         NixOS option documentation does not support headings in general.

     

       42
       42
       -
         :::

     

       43
       43
       -
       

     

       44
       44
       -
       - []{#ssec-contributing-markup-anchors-inline}

     

       45
       45
       -
         **Inline anchors**, which allow linking arbitrary place in the text (e.g. individual list items, sentences…).

     

       46
       46
       -
       

     

       47
       47
       -
         They 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):

     

       48
       48
       -
       

     

       49
       49
       -
         ```markdown

     

       50
       50
       -
         - []{#ssec-gnome-hooks-glib} `glib` setup hook will populate `GSETTINGS_SCHEMAS_PATH` and then `wrapGAppsHook` will prepend it to `XDG_DATA_DIRS`.

     

       51
       51
       -
         ```

     

       52
       52
       -
       

     

       53
       53
       -
       - []{#ssec-contributing-markup-automatic-links}

     

       54
       54
       -
         If you **omit a link text** for a link pointing to a section, the text will be substituted automatically. For example, `[](#chap-contributing)` will result in [](#chap-contributing).

     

       55
       55
       -
       

     

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

     

       57
       57
       -
       

     

       58
       58
       -
       - []{#ssec-contributing-markup-inline-roles}

     

       59
       59
       -
         If you want to link to a man page, you can use `` {manpage}`nix.conf(5)` ``, which will turn into {manpage}`nix.conf(5)`. The references will turn into links when a mapping exists in {file}`doc/manpage-urls.json`.

     

       60
       60
       -
       

     

       61
       61
       -
         A few markups for other kinds of literals are also available:

     

       62
       62
       -
       

     

       63
       63
       -
         - `` {command}`rm -rfi` `` turns into {command}`rm -rfi`

     

       64
       64
       -
         - `` {env}`XDG_DATA_DIRS` `` turns into {env}`XDG_DATA_DIRS`

     

       65
       65
       -
         - `` {file}`/etc/passwd` `` turns into {file}`/etc/passwd`

     

       66
       66
       -
         - `` {option}`networking.useDHCP` `` turns into {option}`networking.useDHCP`

     

       67
       67
       -
         - `` {var}`/etc/passwd` `` turns into {var}`/etc/passwd`

     

       68
       68
       -
       

     

       69
       69
       -
         These literal kinds are used mostly in NixOS option documentation.

     

       70
       70
       -
       

     

       71
       71
       -
         This 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.

     

       72
       72
       -
       

     

       73
       73
       -
       - []{#ssec-contributing-markup-admonitions}

     

       74
       74
       -
         **Admonitions**, set off from the text to bring attention to something.

     

       75
       75
       -
       

     

       76
       76
       -
         It uses pandoc’s [fenced `div`s syntax](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/fenced_divs.md):

     

       77
       77
       -
       

     

       78
       78
       -
         ```markdown

     

       79
       79
       -
         ::: {.warning}

     

       80
       80
       -
         This is a warning

     

       81
       81
       -
         :::

     

       82
       82
       -
         ```

     

       83
       83
       -
       

     

       84
       84
       -
         which renders as

     

       85
       85
       -
       

     

       86
       86
       -
         > ::: {.warning}

     

       87
       87
       -
         > This is a warning.

     

       88
       88
       -
         > :::

     

       89
       89
       -
       

     

       90
       90
       -
         The following are supported:

     

       91
       91
       -
       

     

       92
       92
       -
           - [`caution`](https://tdg.docbook.org/tdg/5.0/caution.html)

     

       93
       93
       -
           - [`important`](https://tdg.docbook.org/tdg/5.0/important.html)

     

       94
       94
       -
           - [`note`](https://tdg.docbook.org/tdg/5.0/note.html)

     

       95
       95
       -
           - [`tip`](https://tdg.docbook.org/tdg/5.0/tip.html)

     

       96
       96
       -
           - [`warning`](https://tdg.docbook.org/tdg/5.0/warning.html)

     

       97
       97
       -
       

     

       98
       98
       -
       - []{#ssec-contributing-markup-definition-lists}

     

       99
       99
       -
         [**Definition lists**](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/definition_lists.md), for defining a group of terms:

     

       100
       100
       -
       

     

       101
       101
       -
         ```markdown

     

       102
       102
       -
         pear

     

       103
       103
       -
         :   green or yellow bulbous fruit

     

       104
       104
       -
       

     

       105
       105
       -
         watermelon

     

       106
       106
       -
         :   green fruit with red flesh

     

       107
       107
       -
         ```

     

       108
       108
       -
       

     

       109
       109
       -
         which renders as

     

       110
       110
       -
       

     

       111
       111
       -
         > pear

     

       112
       112
       -
         > :   green or yellow bulbous fruit

     

       113
       113
       -
         >

     

       114
       114
       -
         > watermelon

     

       115
       115
       -
         > :   green fruit with red flesh

     

       11
       11
       +
       This section has been moved to [doc/README.md](https://github.com/NixOS/nixpkgs/blob/master/doc/README.md).