doc/contributing-to-documentation: Rough move to new contribution doc files
Section in the manual have been preserved with a simple redirect to GitHub, the proper anchors should be filled out in a future commit once the new section names are decided.
This commit is contained in:
Silvan Mosberger
parent
1e1cd398d4
commit
74b17a515f
2 changed files with 119 additions and 107 deletions
116
doc/README.md
116
doc/README.md
|
|
@ -9,3 +9,119 @@ You can find the [rendered documentation for Nixpkgs `unstable` on nixos.org](ht
|
||||||
If you want to contribute to the documentation, [here's how to do it](https://nixos.org/manual/nixpkgs/unstable/#chap-contributing).
|
If you want to contribute to the documentation, [here's how to do it](https://nixos.org/manual/nixpkgs/unstable/#chap-contributing).
|
||||||
|
|
||||||
If you're only getting started with Nix, go to [nixos.org/learn](https://nixos.org/learn).
|
If you're only getting started with Nix, go to [nixos.org/learn](https://nixos.org/learn).
|
||||||
|
|
||||||
|
## Contributing to this documentation {#chap-contributing}
|
||||||
|
|
||||||
|
The sources of the Nixpkgs manual are in the [doc](https://github.com/NixOS/nixpkgs/tree/master/doc) subdirectory of the Nixpkgs repository.
|
||||||
|
|
||||||
|
You can quickly check your edits with `nix-build`:
|
||||||
|
|
||||||
|
```ShellSession
|
||||||
|
$ cd /path/to/nixpkgs
|
||||||
|
$ nix-build doc
|
||||||
|
```
|
||||||
|
|
||||||
|
If the build succeeds, the manual will be in `./result/share/doc/nixpkgs/manual.html`.
|
||||||
|
|
||||||
|
### devmode {#sec-contributing-devmode}
|
||||||
|
|
||||||
|
The shell in the manual source directory makes available a command, `devmode`.
|
||||||
|
It is a daemon, that:
|
||||||
|
1. watches the manual's source for changes and when they occur — rebuilds
|
||||||
|
2. HTTP serves the manual, injecting a script that triggers reload on changes
|
||||||
|
3. opens the manual in the default browser
|
||||||
|
|
||||||
|
### Syntax {#sec-contributing-markup}
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
Additional syntax extensions are available, all of which can be used in NixOS option documentation. The following extensions are currently used:
|
||||||
|
|
||||||
|
- []{#ssec-contributing-markup-tables}
|
||||||
|
Tables, using the [GitHub-flavored Markdown syntax](https://github.github.com/gfm/#tables-extension-).
|
||||||
|
|
||||||
|
- []{#ssec-contributing-markup-anchors}
|
||||||
|
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).
|
||||||
|
|
||||||
|
It uses the widely compatible [header attributes](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/attributes.md) syntax:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Syntax {#sec-contributing-markup}
|
||||||
|
```
|
||||||
|
|
||||||
|
::: {.note}
|
||||||
|
NixOS option documentation does not support headings in general.
|
||||||
|
:::
|
||||||
|
|
||||||
|
- []{#ssec-contributing-markup-anchors-inline}
|
||||||
|
**Inline anchors**, which allow linking arbitrary place in the text (e.g. individual list items, sentences…).
|
||||||
|
|
||||||
|
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):
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
- []{#ssec-gnome-hooks-glib} `glib` setup hook will populate `GSETTINGS_SCHEMAS_PATH` and then `wrapGAppsHook` will prepend it to `XDG_DATA_DIRS`.
|
||||||
|
```
|
||||||
|
|
||||||
|
- []{#ssec-contributing-markup-automatic-links}
|
||||||
|
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).
|
||||||
|
|
||||||
|
This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing).
|
||||||
|
|
||||||
|
- []{#ssec-contributing-markup-inline-roles}
|
||||||
|
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`.
|
||||||
|
|
||||||
|
A few markups for other kinds of literals are also available:
|
||||||
|
|
||||||
|
- `` {command}`rm -rfi` `` turns into {command}`rm -rfi`
|
||||||
|
- `` {env}`XDG_DATA_DIRS` `` turns into {env}`XDG_DATA_DIRS`
|
||||||
|
- `` {file}`/etc/passwd` `` turns into {file}`/etc/passwd`
|
||||||
|
- `` {option}`networking.useDHCP` `` turns into {option}`networking.useDHCP`
|
||||||
|
- `` {var}`/etc/passwd` `` turns into {var}`/etc/passwd`
|
||||||
|
|
||||||
|
These literal kinds are used mostly in NixOS option documentation.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
- []{#ssec-contributing-markup-admonitions}
|
||||||
|
**Admonitions**, set off from the text to bring attention to something.
|
||||||
|
|
||||||
|
It uses pandoc’s [fenced `div`s syntax](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/fenced_divs.md):
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
::: {.warning}
|
||||||
|
This is a warning
|
||||||
|
:::
|
||||||
|
```
|
||||||
|
|
||||||
|
which renders as
|
||||||
|
|
||||||
|
> ::: {.warning}
|
||||||
|
> This is a warning.
|
||||||
|
> :::
|
||||||
|
|
||||||
|
The following are supported:
|
||||||
|
|
||||||
|
- [`caution`](https://tdg.docbook.org/tdg/5.0/caution.html)
|
||||||
|
- [`important`](https://tdg.docbook.org/tdg/5.0/important.html)
|
||||||
|
- [`note`](https://tdg.docbook.org/tdg/5.0/note.html)
|
||||||
|
- [`tip`](https://tdg.docbook.org/tdg/5.0/tip.html)
|
||||||
|
- [`warning`](https://tdg.docbook.org/tdg/5.0/warning.html)
|
||||||
|
|
||||||
|
- []{#ssec-contributing-markup-definition-lists}
|
||||||
|
[**Definition lists**](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/definition_lists.md), for defining a group of terms:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
pear
|
||||||
|
: green or yellow bulbous fruit
|
||||||
|
|
||||||
|
watermelon
|
||||||
|
: green fruit with red flesh
|
||||||
|
```
|
||||||
|
|
||||||
|
which renders as
|
||||||
|
|
||||||
|
> pear
|
||||||
|
> : green or yellow bulbous fruit
|
||||||
|
>
|
||||||
|
> watermelon
|
||||||
|
> : green fruit with red flesh
|
||||||
|
|
|
||||||
|
|
@ -1,115 +1,11 @@
|
||||||
# Contributing to Nixpkgs documentation {#chap-contributing}
|
# Contributing to Nixpkgs documentation {#chap-contributing}
|
||||||
|
|
||||||
The sources of the Nixpkgs manual are in the [doc](https://github.com/NixOS/nixpkgs/tree/master/doc) subdirectory of the Nixpkgs repository.
|
This section has been moved to [doc/README.md](https://github.com/NixOS/nixpkgs/blob/master/doc/README.md).
|
||||||
|
|
||||||
You can quickly check your edits with `nix-build`:
|
|
||||||
|
|
||||||
```ShellSession
|
|
||||||
$ cd /path/to/nixpkgs
|
|
||||||
$ nix-build doc
|
|
||||||
```
|
|
||||||
|
|
||||||
If the build succeeds, the manual will be in `./result/share/doc/nixpkgs/manual.html`.
|
|
||||||
|
|
||||||
## devmode {#sec-contributing-devmode}
|
## devmode {#sec-contributing-devmode}
|
||||||
|
|
||||||
The shell in the manual source directory makes available a command, `devmode`.
|
This section has been moved to [doc/README.md](https://github.com/NixOS/nixpkgs/blob/master/doc/README.md).
|
||||||
It is a daemon, that:
|
|
||||||
1. watches the manual's source for changes and when they occur — rebuilds
|
|
||||||
2. HTTP serves the manual, injecting a script that triggers reload on changes
|
|
||||||
3. opens the manual in the default browser
|
|
||||||
|
|
||||||
## Syntax {#sec-contributing-markup}
|
## Syntax {#sec-contributing-markup}
|
||||||
|
|
||||||
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.
|
This section has been moved to [doc/README.md](https://github.com/NixOS/nixpkgs/blob/master/doc/README.md).
|
||||||
|
|
||||||
Additional syntax extensions are available, all of which can be used in NixOS option documentation. The following extensions are currently used:
|
|
||||||
|
|
||||||
- []{#ssec-contributing-markup-tables}
|
|
||||||
Tables, using the [GitHub-flavored Markdown syntax](https://github.github.com/gfm/#tables-extension-).
|
|
||||||
|
|
||||||
- []{#ssec-contributing-markup-anchors}
|
|
||||||
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).
|
|
||||||
|
|
||||||
It uses the widely compatible [header attributes](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/attributes.md) syntax:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
## Syntax {#sec-contributing-markup}
|
|
||||||
```
|
|
||||||
|
|
||||||
::: {.note}
|
|
||||||
NixOS option documentation does not support headings in general.
|
|
||||||
:::
|
|
||||||
|
|
||||||
- []{#ssec-contributing-markup-anchors-inline}
|
|
||||||
**Inline anchors**, which allow linking arbitrary place in the text (e.g. individual list items, sentences…).
|
|
||||||
|
|
||||||
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):
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
- []{#ssec-gnome-hooks-glib} `glib` setup hook will populate `GSETTINGS_SCHEMAS_PATH` and then `wrapGAppsHook` will prepend it to `XDG_DATA_DIRS`.
|
|
||||||
```
|
|
||||||
|
|
||||||
- []{#ssec-contributing-markup-automatic-links}
|
|
||||||
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).
|
|
||||||
|
|
||||||
This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing).
|
|
||||||
|
|
||||||
- []{#ssec-contributing-markup-inline-roles}
|
|
||||||
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`.
|
|
||||||
|
|
||||||
A few markups for other kinds of literals are also available:
|
|
||||||
|
|
||||||
- `` {command}`rm -rfi` `` turns into {command}`rm -rfi`
|
|
||||||
- `` {env}`XDG_DATA_DIRS` `` turns into {env}`XDG_DATA_DIRS`
|
|
||||||
- `` {file}`/etc/passwd` `` turns into {file}`/etc/passwd`
|
|
||||||
- `` {option}`networking.useDHCP` `` turns into {option}`networking.useDHCP`
|
|
||||||
- `` {var}`/etc/passwd` `` turns into {var}`/etc/passwd`
|
|
||||||
|
|
||||||
These literal kinds are used mostly in NixOS option documentation.
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
- []{#ssec-contributing-markup-admonitions}
|
|
||||||
**Admonitions**, set off from the text to bring attention to something.
|
|
||||||
|
|
||||||
It uses pandoc’s [fenced `div`s syntax](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/fenced_divs.md):
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
::: {.warning}
|
|
||||||
This is a warning
|
|
||||||
:::
|
|
||||||
```
|
|
||||||
|
|
||||||
which renders as
|
|
||||||
|
|
||||||
> ::: {.warning}
|
|
||||||
> This is a warning.
|
|
||||||
> :::
|
|
||||||
|
|
||||||
The following are supported:
|
|
||||||
|
|
||||||
- [`caution`](https://tdg.docbook.org/tdg/5.0/caution.html)
|
|
||||||
- [`important`](https://tdg.docbook.org/tdg/5.0/important.html)
|
|
||||||
- [`note`](https://tdg.docbook.org/tdg/5.0/note.html)
|
|
||||||
- [`tip`](https://tdg.docbook.org/tdg/5.0/tip.html)
|
|
||||||
- [`warning`](https://tdg.docbook.org/tdg/5.0/warning.html)
|
|
||||||
|
|
||||||
- []{#ssec-contributing-markup-definition-lists}
|
|
||||||
[**Definition lists**](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/definition_lists.md), for defining a group of terms:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
pear
|
|
||||||
: green or yellow bulbous fruit
|
|
||||||
|
|
||||||
watermelon
|
|
||||||
: green fruit with red flesh
|
|
||||||
```
|
|
||||||
|
|
||||||
which renders as
|
|
||||||
|
|
||||||
> pear
|
|
||||||
> : green or yellow bulbous fruit
|
|
||||||
>
|
|
||||||
> watermelon
|
|
||||||
> : green fruit with red flesh
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue