nixpkgs/doc
Connor Baker d5e5246e76 cudaPackages: split outputs
This change which involves creating multiple outputs for CUDA
redistributable packages.

We use a script to find out, ahead of time, the outputs each redist
package provides. From that, we are able to create multiple outputs for
supported redist packages, allowing users to specify exactly which
components they require.

Beyond the script which finds outputs ahead of time, there is some custom
code involved in making this happen. For example, the way Nixpkgs
typically handles multiple outputs involves making `dev` the default
output when available, and adding `out` to `dev`'s
`propagatedBuildInputs`.

Instead, we make each output independent of the others. If a user wants
only to include the headers found in a redist package, they can do so by
choosing the `dev` output. If they want to include dynamic libraries,
they can do so by specifying the `lib` output, or `static` for static
libraries.

To avoid breakages, we continue to provide the `out` output, which
becomes the union of all other outputs, effectively making the split
outputs opt-in.
2023-08-31 03:31:55 +00:00
..
builders doc/fetchers: fetchDebianPatch: don't imply how long a patch remains available 2023-08-30 08:06:10 +00:00
contributing doc/vulnerability-roundup: Rough move to new contribution doc files 2023-08-13 22:04:56 +02:00
development CONTRIBUTING.md: Move opening issues section to Nixpkgs manual 2023-08-13 22:04:57 +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 Merge master into staging-next 2023-08-26 12:01:05 +00:00
languages-frameworks cudaPackages: split outputs 2023-08-31 03:31:55 +00:00
module-system lib.modules: configurationClass -> class 2023-05-06 18:32:59 +02:00
old doc: fix typos 2022-12-17 18:21:48 -05:00
stdenv Merge pull request #245583 from galenhuntington/doc-fix 2023-08-29 22:46:56 +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 lib/gvariant: init 2023-08-15 19:20:39 +08:00
development.md CONTRIBUTING.md: Move opening issues section to Nixpkgs manual 2023-08-13 22:04:57 +02: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 Remove unused reference 2023-04-09 21:56:55 +02:00
manual.md.in doc: Add empty development section 2023-08-13 22:04:56 +02:00
overrides.css
preface.chapter.md updating stable nixos version in preface. 2023-01-05 22:24:19 +00:00
README.md doc/README.md: Cleanup 2023-08-14 04:46:16 +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'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:

  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:

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`.

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 pandocs 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