Merge pull request #176146 from pennae/module-docs-markdown

      content = '<refentrytitle>' .. title .. '</refentrytitle>' .. (volnum ~= nil and ('<manvolnum>' .. volnum .. '</manvolnum>') or '')

    elseif elem.attributes['role'] == 'file' then

      tag = 'filename'

    elseif elem.attributes['role'] == 'command' then

      tag = 'command'

    elseif elem.attributes['role'] == 'option' then

      tag = 'option'

    end

    if tag ~= nil then

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.

Additionally, the following syntax extensions are currently used:

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](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/auto_identifiers.md).

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

  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/build-aux/pandoc-filters/link-unix-man-references.lua`.

  The references will turn into links when a mapping exists in {file}`doc/build-aux/pandoc-filters/link-unix-man-references.lua`.

  A few markups for other kinds of literals are also available:

  - `` {command}`rm -rfi` `` turns into {command}`rm -rfi`

  - `` {option}`networking.useDHCP` `` turns into {option}`networking.useDHCP`

  - `` {file}`/etc/passwd` `` turns into {file}`/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.

  ::: {.note}

  Inline roles are available for option documentation.

  :::

- []{#ssec-contributing-markup-admonitions}

  **Admonitions**, set off from the text to bring attention to something.

    - [`tip`](https://tdg.docbook.org/tdg/5.0/tip.html)

    - [`warning`](https://tdg.docbook.org/tdg/5.0/warning.html)

  ::: {.note}

  Admonitions are available for option documentation.

  :::

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

      getValues getFiles

      optionAttrSetToDocList optionAttrSetToDocList'

      scrubOptionValue literalExpression literalExample literalDocBook

      showOption showFiles unknownModule mkOption mkPackageOption;

      showOption showFiles unknownModule mkOption mkPackageOption

      mdDoc literalMD;

    inherit (self.types) isType setType defaultTypeMerge defaultFunctor

      isOptionType mkOptionType;

    inherit (self.asserts)

    if ! isString text then throw "literalDocBook expects a string."

    else { _type = "literalDocBook"; inherit text; };

  /* Transition marker for documentation that's already migrated to markdown

     syntax.

  */

  mdDoc = text:

    if ! isString text then throw "mdDoc expects a string."

    else { _type = "mdDoc"; inherit text; };

  /* For use in the `defaultText` and `example` option attributes. Causes the

     given MD text to be inserted verbatim in the documentation, for when

     a `literalExpression` would be too hard to read.

  */

  literalMD = text:

    if ! isString text then throw "literalMD expects a string."

    else { _type = "literalMD"; inherit text; };

  # Helper functions.

  /* Convert an option, described as a list of the option parts in to a

`description`

:   A textual description of the option, in DocBook format, that will be

    included in the NixOS manual.

    included in the NixOS manual. During the migration process from DocBook

    to CommonMark the description may also be written in CommonMark, but has

    to be wrapped in `lib.mdDoc` to differentiate it from DocBook. See

    the nixpkgs manual for [the list of CommonMark extensions](

    https://nixos.org/nixpkgs/manual/#sec-contributing-markup)

    supported by NixOS documentation.

    New documentation should preferably be written as CommonMark.

## Utility functions for common option patterns {#sec-option-declarations-util}