From 74b17a515f8fb8cb59e54bf21e7be4861e239009 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Tue, 25 Jul 2023 17:51:38 +0200 Subject: [PATCH] doc/contributing-to-documentation: Rough move to new contribution doc files 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. --- doc/README.md | 116 ++++++++++++++++++ .../contributing-to-documentation.chapter.md | 110 +---------------- 2 files changed, 119 insertions(+), 107 deletions(-) diff --git a/doc/README.md b/doc/README.md index eea797403808..19b61233bc28 100644 --- a/doc/README.md +++ b/doc/README.md @@ -9,3 +9,119 @@ You can find the [rendered documentation for Nixpkgs `unstable` on nixos.org](ht If you want to contribute to the documentation, [here's how to do it](https://nixos.org/manual/nixpkgs/unstable/#chap-contributing). If you're only getting started with Nix, go to [nixos.org/learn](https://nixos.org/learn). + +## Contributing to this documentation {#chap-contributing} + +The sources of the Nixpkgs manual are in the [doc](https://github.com/NixOS/nixpkgs/tree/master/doc) subdirectory of the Nixpkgs repository. + +You can quickly check your edits with `nix-build`: + +```ShellSession +$ cd /path/to/nixpkgs +$ nix-build doc +``` + +If the build succeeds, the manual will be in `./result/share/doc/nixpkgs/manual.html`. + +### devmode {#sec-contributing-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 {#sec-contributing-markup} + +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. + +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](https://github.github.com/gfm/#tables-extension-). + +- []{#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). + + It uses the widely compatible [header attributes](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/attributes.md) syntax: + + ```markdown + ## 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](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/bracketed_spans.md): + + ```markdown + - []{#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 [](#chap-contributing). + + 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)`. 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](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. + +- []{#ssec-contributing-markup-admonitions} + **Admonitions**, set off from the text to bring attention to something. + + It uses pandoc’s [fenced `div`s syntax](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/fenced_divs.md): + + ```markdown + ::: {.warning} + This is a warning + ::: + ``` + + which renders as + + > ::: {.warning} + > This is a warning. + > ::: + + The following are supported: + + - [`caution`](https://tdg.docbook.org/tdg/5.0/caution.html) + - [`important`](https://tdg.docbook.org/tdg/5.0/important.html) + - [`note`](https://tdg.docbook.org/tdg/5.0/note.html) + - [`tip`](https://tdg.docbook.org/tdg/5.0/tip.html) + - [`warning`](https://tdg.docbook.org/tdg/5.0/warning.html) + +- []{#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: + + ```markdown + 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 diff --git a/doc/contributing/contributing-to-documentation.chapter.md b/doc/contributing/contributing-to-documentation.chapter.md index 09cc3160df3c..777858b901c3 100644 --- a/doc/contributing/contributing-to-documentation.chapter.md +++ b/doc/contributing/contributing-to-documentation.chapter.md @@ -1,115 +1,11 @@ # Contributing to Nixpkgs documentation {#chap-contributing} -The sources of the Nixpkgs manual are in the [doc](https://github.com/NixOS/nixpkgs/tree/master/doc) subdirectory of the Nixpkgs repository. - -You can quickly check your edits with `nix-build`: - -```ShellSession -$ cd /path/to/nixpkgs -$ nix-build doc -``` - -If the build succeeds, the manual will be in `./result/share/doc/nixpkgs/manual.html`. +This section has been moved to [doc/README.md](https://github.com/NixOS/nixpkgs/blob/master/doc/README.md). ## devmode {#sec-contributing-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 +This section has been moved to [doc/README.md](https://github.com/NixOS/nixpkgs/blob/master/doc/README.md). ## Syntax {#sec-contributing-markup} -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. - -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](https://github.github.com/gfm/#tables-extension-). - -- []{#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). - - It uses the widely compatible [header attributes](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/attributes.md) syntax: - - ```markdown - ## 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](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/bracketed_spans.md): - - ```markdown - - []{#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 [](#chap-contributing). - - 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)`. 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](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. - -- []{#ssec-contributing-markup-admonitions} - **Admonitions**, set off from the text to bring attention to something. - - It uses pandoc’s [fenced `div`s syntax](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/fenced_divs.md): - - ```markdown - ::: {.warning} - This is a warning - ::: - ``` - - which renders as - - > ::: {.warning} - > This is a warning. - > ::: - - The following are supported: - - - [`caution`](https://tdg.docbook.org/tdg/5.0/caution.html) - - [`important`](https://tdg.docbook.org/tdg/5.0/important.html) - - [`note`](https://tdg.docbook.org/tdg/5.0/note.html) - - [`tip`](https://tdg.docbook.org/tdg/5.0/tip.html) - - [`warning`](https://tdg.docbook.org/tdg/5.0/warning.html) - -- []{#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: - - ```markdown - 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 +This section has been moved to [doc/README.md](https://github.com/NixOS/nixpkgs/blob/master/doc/README.md).