From 6ab2a5da2353f7c7f4ba74b532c7b6870782960f Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Mon, 15 Dec 2025 09:36:35 +0100 Subject: [PATCH 1/3] doc: collapse old contributing sections to one redirect also link from nixos/doc to the in-tree README directly --- doc/contributing/contributing-to-documentation.chapter.md | 8 -------- doc/redirects.json | 8 ++------ nixos/doc/manual/contributing-to-this-manual.chapter.md | 2 +- 3 files changed, 3 insertions(+), 15 deletions(-) diff --git a/doc/contributing/contributing-to-documentation.chapter.md b/doc/contributing/contributing-to-documentation.chapter.md index 777858b901c3..54f7ebcb41b9 100644 --- a/doc/contributing/contributing-to-documentation.chapter.md +++ b/doc/contributing/contributing-to-documentation.chapter.md @@ -1,11 +1,3 @@ # Contributing to Nixpkgs documentation {#chap-contributing} This section has been moved to [doc/README.md](https://github.com/NixOS/nixpkgs/blob/master/doc/README.md). - -## devmode {#sec-contributing-devmode} - -This section has been moved to [doc/README.md](https://github.com/NixOS/nixpkgs/blob/master/doc/README.md). - -## Syntax {#sec-contributing-markup} - -This section has been moved to [doc/README.md](https://github.com/NixOS/nixpkgs/blob/master/doc/README.md). diff --git a/doc/redirects.json b/doc/redirects.json index f0e7f455d6a5..ffa10799fa6f 100644 --- a/doc/redirects.json +++ b/doc/redirects.json @@ -4663,12 +4663,8 @@ "index.html#reviewing-contributions--merging-pull-requests" ], "chap-contributing": [ - "index.html#chap-contributing" - ], - "sec-contributing-devmode": [ - "index.html#sec-contributing-devmode" - ], - "sec-contributing-markup": [ + "index.html#chap-contributing", + "index.html#sec-contributing-devmode", "index.html#sec-contributing-markup" ], "part-interoperability": [ diff --git a/nixos/doc/manual/contributing-to-this-manual.chapter.md b/nixos/doc/manual/contributing-to-this-manual.chapter.md index 1b296918f9e2..3a7d9a4f61a5 100644 --- a/nixos/doc/manual/contributing-to-this-manual.chapter.md +++ b/nixos/doc/manual/contributing-to-this-manual.chapter.md @@ -1,7 +1,7 @@ # Contributing to this manual {#chap-contributing} The sources of the NixOS manual are in the [nixos/doc/manual](https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual) subdirectory of the [Nixpkgs](https://github.com/NixOS/nixpkgs) repository. -This manual uses the [Nixpkgs manual syntax](https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup). +This manual uses the [Nixpkgs manual syntax](https://github.com/NixOS/nixpkgs/blob/master/doc/README.md#syntax). You can quickly check your edits with the following: From 2d66ed0c663c44db886d7cd4e2b39b4a937d943c Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Mon, 15 Dec 2025 09:43:21 +0100 Subject: [PATCH 2/3] nixos/doc: don't link to Nixpkgs devmode guide there's an inline copy of the same instructions --- nixos/doc/manual/contributing-to-this-manual.chapter.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/nixos/doc/manual/contributing-to-this-manual.chapter.md b/nixos/doc/manual/contributing-to-this-manual.chapter.md index 3a7d9a4f61a5..778e707a1396 100644 --- a/nixos/doc/manual/contributing-to-this-manual.chapter.md +++ b/nixos/doc/manual/contributing-to-this-manual.chapter.md @@ -13,8 +13,6 @@ $ nix-build nixos/release.nix -A manual.x86_64-linux If the build succeeds, the manual will be in `./result/share/doc/nixos/index.html`. -There's also [a convenient development daemon](https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-devmode). - The above instructions don't deal with the appendix of available `configuration.nix` options, and the manual pages related to NixOS. These are built, and written in a different location and in a different format, as explained in the next sections. ## Development environment {#sec-contributing-development-env} From 308ca19afa39d0c8023b549ae76b7142298ccc8a Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Mon, 15 Dec 2025 09:49:35 +0100 Subject: [PATCH 3/3] doc: add note on updating existing content to one-sentence-one-line --- doc/README.md | 4 ++++ nixos/doc/manual/contributing-to-this-manual.chapter.md | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/README.md b/doc/README.md index 889198bc9e35..6ac3edc8af62 100644 --- a/doc/README.md +++ b/doc/README.md @@ -213,6 +213,10 @@ Put each sentence in its own line. This makes reviews and suggestions much easier, since GitHub's review system is based on lines. It also helps identifying long sentences at a glance. +Not everything has been migrated to this format yet. +Please always use it for new content. +When changing existing content, update formatting if possible, but avoid excessive diffs. + ### Writing Function Documentation Function documentation is *reference documentation*, for which diff --git a/nixos/doc/manual/contributing-to-this-manual.chapter.md b/nixos/doc/manual/contributing-to-this-manual.chapter.md index 778e707a1396..bf8aea99efef 100644 --- a/nixos/doc/manual/contributing-to-this-manual.chapter.md +++ b/nixos/doc/manual/contributing-to-this-manual.chapter.md @@ -1,7 +1,7 @@ # Contributing to this manual {#chap-contributing} The sources of the NixOS manual are in the [nixos/doc/manual](https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual) subdirectory of the [Nixpkgs](https://github.com/NixOS/nixpkgs) repository. -This manual uses the [Nixpkgs manual syntax](https://github.com/NixOS/nixpkgs/blob/master/doc/README.md#syntax). +This manual uses the [Nixpkgs manual syntax](https://github.com/NixOS/nixpkgs/blob/master/doc/README.md#syntax) and [stylistic conventions](https://github.com/NixOS/nixpkgs/blob/master/doc/README.md#documentation-conventions). You can quickly check your edits with the following: