0504bc63e4
* doc/stdenv: rewrite manual build procedure to be closer to an auto-build This is based on <https://jade.fyi/blog/building-nix-derivations-manually/> plus some more original research. The previous version of this section did not work for your choice of simple Haskell package, e.g. haskellPackages.hscolour, due to things like `compileBuildDriverPhase` and other custom phases that it does not address at all. It seems more correct to use genericBuild in development to harmonize it with what is actually done. I feel a little bit like I am committing a sin by suggesting using the experimental CLI in the manual (afaict I am the first to do this), but I have given the old version of the command, and there are justifiable reasons to do it: * The noted limitations with env-vars are fixed. The one with the non-empty temp directory was one I ran into myself and oh boy was that not fun to debug. * Additionally the outputs are set *before* sourcing `setup.sh`: there is an issue with nix-shell where the original version of `$out` winds up in `NIX_LDFLAGS` due to _addRpathPrefix, which means that resulting executables may not run properly. It is sad that `nix develop` propagates a wrong value of `SHELL` to builders, though. It is equally sad that `nix-shell` is essentially abandoned upstream, with undocumented and not insignificant differences from `nix develop`. For the exact script differences: |
||
|---|---|---|
| .. | ||
| builders | ||
| contributing | ||
| development | ||
| doc-support | ||
| functions | ||
| hooks | ||
| languages-frameworks | ||
| module-system | ||
| old | ||
| stdenv | ||
| using | ||
| builders.md | ||
| common.nix | ||
| contributing.md | ||
| default.nix | ||
| development.md | ||
| functions.md | ||
| lib.md | ||
| manpage-urls.json | ||
| manual.md.in | ||
| overrides.css | ||
| preface.chapter.md | ||
| README.md | ||
| shell.nix | ||
| stdenv.md | ||
| style.css | ||
| using-nixpkgs.md | ||
Contributing to the Nixpkgs manual
This directory houses the sources files for the Nixpkgs manual.
You can find the rendered documentation for Nixpkgs unstable on nixos.org.
The rendering tool is nixos-render-docs, sometimes abbreviated nrd.
Docs for Nixpkgs stable are also available.
If you're only getting started with Nix, go to nixos.org/learn.
Contributing to this documentation
You can quickly check your edits with nix-build:
$ cd /path/to/nixpkgs
$ nix-build doc
If the build succeeds, the manual will be in ./result/share/doc/nixpkgs/manual.html.
devmode
The shell in the manual source directory makes available a command, devmode.
It is a daemon, that:
- watches the manual's source for changes and when they occur — rebuilds
- HTTP serves the manual, injecting a script that triggers reload on changes
- opens the manual in the default browser
Syntax
As per RFC 0072, all new documentation content should be written in CommonMark Markdown dialect.
Additional syntax extensions are available, all of which can be used in NixOS option documentation. The following extensions are currently used:
Tables
Tables, using the GitHub-flavored Markdown syntax.
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}
Note
NixOS option documentation does not support headings in general.
Inline Anchors
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`.
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).
This syntax is taken from MyST.
Roles
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.
A few markups for other kinds of literals are also available:
{command}`rm -rfi`{env}`XDG_DATA_DIRS`{file}`/etc/passwd`{option}`networking.useDHCP`{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.
Admonitions
Set off from the text to bring attention to something.
It uses pandoc’s fenced divs syntax:
::: {.warning}
This is a warning
:::
The following are supported:
Definition lists
For defining a group of terms:
pear
: green or yellow bulbous fruit
watermelon
: green fruit with red flesh