From 50ae421edda20e17692c6f512e9b0d18e7641651 Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Thu, 19 Sep 2024 09:35:33 +0200 Subject: [PATCH 1/3] Docs: highlight structure vision --- doc/README.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/doc/README.md b/doc/README.md index 211f986b851d8..f2b8ffe4a0e94 100644 --- a/doc/README.md +++ b/doc/README.md @@ -2,10 +2,18 @@ This directory houses the sources files for the Nixpkgs reference manual. -Going forward, it should only contain [reference](https://nix.dev/contributing/documentation/diataxis#reference) documentation. -For tutorials, guides and explanations, contribute to instead. - -For documentation only relevant for contributors, use Markdown files and code comments in the source code. +> [!IMPORTANT] +> We are actively restructuring our documentation to follow the [Diátaxis framework](https://diataxis.fr/) +> +> Going forward, this folder should only contain **[reference](https://nix.dev/contributing/documentation/diataxis#reference) documentation**. +> For tutorials, guides and explanations, contribute to instead. +> +> We are actively working to generate **all** reference documentation from the [doc-comments](https://github.com/NixOS/rfcs/blob/master/rfcs/0145-doc-strings.md) present in code. +> This also provides the benefit of using `:doc` in the `nix repl` to view reference documentation locally on the fly. + +For reference documentation prefer Markdown files and code comments in the source code if supported yet. + +> We'are actively soliciting feedback for missing support. If your case is not supported open an issue starting with `Doc:` Rendered documentation: - [Unstable (from master)](https://nixos.org/manual/nixpkgs/unstable/) From 5d4d9258891cc7db2ce7fa9ad1dd473048968ab9 Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Thu, 19 Sep 2024 15:14:54 +0200 Subject: [PATCH 2/3] Update doc/README.md Co-authored-by: Valentin Gagarin --- doc/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/README.md b/doc/README.md index f2b8ffe4a0e94..63e50a97a768c 100644 --- a/doc/README.md +++ b/doc/README.md @@ -5,7 +5,7 @@ This directory houses the sources files for the Nixpkgs reference manual. > [!IMPORTANT] > We are actively restructuring our documentation to follow the [Diátaxis framework](https://diataxis.fr/) > -> Going forward, this folder should only contain **[reference](https://nix.dev/contributing/documentation/diataxis#reference) documentation**. +> Going forward, this directory should **only** contain [reference documentation](https://nix.dev/contributing/documentation/diataxis#reference). > For tutorials, guides and explanations, contribute to instead. > > We are actively working to generate **all** reference documentation from the [doc-comments](https://github.com/NixOS/rfcs/blob/master/rfcs/0145-doc-strings.md) present in code. From 5271060e28d2c30e52ef2eb16b961728ee4d3688 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Thu, 19 Sep 2024 19:57:02 +0200 Subject: [PATCH 3/3] Apply suggestions from code review --- doc/README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/README.md b/doc/README.md index 63e50a97a768c..534fc92de5a8f 100644 --- a/doc/README.md +++ b/doc/README.md @@ -11,9 +11,11 @@ This directory houses the sources files for the Nixpkgs reference manual. > We are actively working to generate **all** reference documentation from the [doc-comments](https://github.com/NixOS/rfcs/blob/master/rfcs/0145-doc-strings.md) present in code. > This also provides the benefit of using `:doc` in the `nix repl` to view reference documentation locally on the fly. -For reference documentation prefer Markdown files and code comments in the source code if supported yet. +For documentation only relevant for contributors, use Markdown files next to the source and regular code comments. -> We'are actively soliciting feedback for missing support. If your case is not supported open an issue starting with `Doc:` +> [!TIP] +> Feedback for improving support for parsing and rendering doc-comments is highly appreciated. +> [Open an issue](https://github.com/NixOS/nixpkgs/issues/new?labels=6.topic%3A+documentation&title=Doc%3A+) to request bugfixes or new features. Rendered documentation: - [Unstable (from master)](https://nixos.org/manual/nixpkgs/unstable/)