a8d4cf149c
Move the manpage-to-URL mapping to `doc/manpage-urls.json` so that we can reuse that file elsewhere, and generate the `link-manpages.lua` filter from that file. Also modify the Pandoc filter so that it doesn't wrap manpages that are already inside a link. Keeping a Lua filter is essential for speed: a Python filter would increase the runtime `md-to-db.sh` from ~20s to ~30s (but Python is not to blame; marshalling Pandoc types to and from JSON is a costly operation). Parsing in Lua seems tedious, so I went with the Nix way.
5.2 KiB
Contributing to this documentation
The sources of the Nixpkgs manual are in the doc subdirectory of the Nixpkgs repository. The manual is still partially written in DocBook but it is progressively being converted to Markdown.
You can quickly check your edits with make:
$ cd /path/to/nixpkgs/doc
$ nix-shell
[nix-shell]$ make
If you experience problems, run make debug to help understand the docbook errors.
After making modifications to the manual, it's important to build it before committing. You can do that as follows:
$ cd /path/to/nixpkgs/doc
$ nix-shell
[nix-shell]$ make clean
[nix-shell]$ nix-build .
If the build succeeds, the manual will be in ./result/share/doc/nixpkgs/manual.html.
Syntax
As per RFC 0072, all new documentation content should be written in CommonMark Markdown dialect.
Additional syntax extensions are available, though not all extensions can be used in NixOS option documentation. The following extensions are currently used:
-
[]{#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.
It uses the widely compatible header attributes syntax:
## Syntax {#sec-contributing-markup} -
[]{#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:
- []{#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 .This syntax is taken from MyST.
-
[]{#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. Though, the feature originates from reStructuredText with slightly different syntax.
::: {.note} Inline roles are available for option documentation. :::
-
[]{#ssec-contributing-markup-admonitions} Admonitions, set off from the text to bring attention to something.
It uses pandoc’s fenced
divs syntax:::: {.warning} This is a warning :::which renders as
::: {.warning} This is a warning. :::
The following are supported:
::: {.note} Admonitions are available for option documentation. :::
-
[]{#ssec-contributing-markup-definition-lists} Definition lists, for defining a group of terms:
pear : green or yellow bulbous fruit watermelon : green fruit with red fleshwhich renders as
- pear
- green or yellow bulbous fruit
- watermelon
- green fruit with red flesh
For contributing to the legacy parts, please see DocBook: The Definitive Guide or the DocBook rocks! primer.