nixpkgs/doc
Silvan Mosberger f3a050a191 doc/reviewing-contributions: Rough move to new contribution doc files
No content was changed, new titles are wrapped with () to signal that
they will need to be decided on in a future commit.

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.
2023-08-13 22:04:56 +02:00
..
builders testers.hasPkgConfigModules: allow checking multiple pkg-config mods 2023-08-08 19:16:48 +02:00
contributing doc/reviewing-contributions: Rough move to new contribution doc files 2023-08-13 22:04:56 +02:00
doc-support doc: Render lib.fixedPoints 2023-07-08 18:46:08 +02:00
functions doc: render nixpkgs manual with nrd 2023-07-01 20:59:29 +02:00
hooks treewide: use zig_0_11 instead of zig for zig packages 2023-08-10 02:37:53 +00:00
languages-frameworks Merge master into staging-next 2023-08-08 00:01:49 +00:00
module-system lib.modules: configurationClass -> class 2023-05-06 18:32:59 +02:00
old
stdenv treewide: update mainProgram docs 2023-08-04 20:31:16 +03:00
using Merge pull request #239636 from pennae/nixpkgs-manual-nrd 2023-07-03 20:48:23 +02:00
builders.md doc: render nixpkgs manual with nrd 2023-07-01 20:59:29 +02:00
common.nix nixpkgs manual: extract some build paths 2023-07-25 17:00:51 +07:00
contributing.md doc: render nixpkgs manual with nrd 2023-07-01 20:59:29 +02:00
default.nix nixpkgs manual: extract some build paths 2023-07-25 17:00:51 +07:00
functions.md doc: render nixpkgs manual with nrd 2023-07-01 20:59:29 +02:00
lib.md doc: render nixpkgs manual with nrd 2023-07-01 20:59:29 +02:00
manpage-urls.json
manual.md.in doc: render nixpkgs manual with nrd 2023-07-01 20:59:29 +02:00
overrides.css
preface.chapter.md
README.md doc/contributing-to-documentation: Rough move to new contribution doc files 2023-08-13 22:04:55 +02:00
shell.nix nixpkgs/NixOS manuals: devmode feature 2023-07-25 17:03:15 +07:00
stdenv.md doc: render nixpkgs manual with nrd 2023-07-01 20:59:29 +02:00
style.css
using-nixpkgs.md doc: render nixpkgs manual with nrd 2023-07-01 20:59:29 +02:00

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.

Docs for Nixpkgs stable are also available.

If you want to contribute to the documentation, here's how to do it.

If you're only getting started with Nix, go to nixos.org/learn.

Contributing to this documentation

The sources of the Nixpkgs manual are in the doc subdirectory of the Nixpkgs repository.

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:

  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

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:

  • []{#ssec-contributing-markup-tables} Tables, using the GitHub-flavored Markdown syntax.

  • []{#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}
    

    ::: {.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:

    - []{#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.

  • []{#ssec-contributing-markup-admonitions} Admonitions, set off from the text to bring attention to something.

    It uses pandocs fenced divs syntax:

    ::: {.warning}
    This is a warning
    :::
    

    which renders as

    ::: {.warning} This is a warning. :::

    The following are supported:

  • []{#ssec-contributing-markup-definition-lists} Definition lists, for defining a group of terms:

    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