diff --git a/.github/workflows/backport.yml b/.github/workflows/backport.yml index a769a95de428..5805401b08c7 100644 --- a/.github/workflows/backport.yml +++ b/.github/workflows/backport.yml @@ -49,7 +49,7 @@ jobs: - name: Create backport PRs id: backport - uses: korthout/backport-action@66065406958f46e82238fd59546f5a99e69e22aa # v4.5.2 + uses: korthout/backport-action@2e830a1d0b8269505846ddd407a70876913ad1f8 # v4.6.0 with: # Config README: https://github.com/korthout/backport-action#backport-action add_author_as_reviewer: true diff --git a/ci/OWNERS b/ci/OWNERS index e6e3bb388348..742d7839f5d4 100644 --- a/ci/OWNERS +++ b/ci/OWNERS @@ -506,7 +506,7 @@ pkgs/by-name/oc/octodns/ @anthonyroussel pkgs/by-name/te/teleport* @arianvp @justinas @sigma @tomberek @techknowlogick @JuliusFreudenberger # Warp-terminal -pkgs/by-name/wa/warp-terminal/ @emilytrau @imadnyc @4evy @johnrtitor +pkgs/by-name/wa/warp-terminal/ @emilytrau @imadnyc @FlameFlag @johnrtitor # Nim /doc/languages-frameworks/nim.section.md @NixOS/nim diff --git a/ci/default.nix b/ci/default.nix index 06fa75bbc38f..6aa80f977901 100644 --- a/ci/default.nix +++ b/ci/default.nix @@ -70,7 +70,7 @@ rec { }; parse = pkgs.lib.recurseIntoAttrs { nix_latest = pkgs.callPackage ./parse.nix { nix = pkgs.nixVersions.latest; }; - stable = pkgs.callPackage ./parse.nix { nix = pkgs.nixVersions.stable; }; + nix_2_28 = pkgs.callPackage ./parse.nix { nix = pkgs.nixVersions.nix_2_28; }; lix = pkgs.callPackage ./parse.nix { nix = pkgs.lix; }; lix_latest = pkgs.callPackage ./parse.nix { nix = pkgs.lixPackageSets.latest.lix; }; }; diff --git a/ci/pinned.json b/ci/pinned.json index 0b3d817d1b06..fc034a85bccf 100644 --- a/ci/pinned.json +++ b/ci/pinned.json @@ -9,9 +9,9 @@ }, "branch": "nixpkgs-unstable", "submodules": false, - "revision": "6edbf1a6a03e75886a6609c088801a0856449e88", - "url": "https://github.com/NixOS/nixpkgs/archive/6edbf1a6a03e75886a6609c088801a0856449e88.tar.gz", - "hash": "sha256-0lkauQbtrljJqwtzTCILPAiHAJyMvn6XDo264moDv30=" + "revision": "8c91a71d13451abc40eb9dae8910f972f979852f", + "url": "https://github.com/NixOS/nixpkgs/archive/8c91a71d13451abc40eb9dae8910f972f979852f.tar.gz", + "hash": "sha256-fnzKKPvS+oieI/pTzotA5tkoM47EB1NpaBcgk4R97hE=" } }, "version": 8 diff --git a/ci/update-pinned.sh b/ci/update-pinned.sh index 51c99b0da98d..69ba7df9131d 100755 --- a/ci/update-pinned.sh +++ b/ci/update-pinned.sh @@ -1,5 +1,5 @@ #!/usr/bin/env nix-shell -#!nix-shell -i bash -E 'with import ../. {}; mkShell { packages = [ npins ]; }' +#!nix-shell -i bash -p npins -I nixpkgs=../ set -euo pipefail diff --git a/doc/README.md b/doc/README.md index 4b124deaa3ce..84f2519d35ef 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,32 +1,21 @@ -# Contributing to the Nixpkgs manual +# Contributing to the Nixpkgs reference manual -This directory houses the source files for the Nixpkgs manual. +This directory houses the source files for the Nixpkgs reference manual. -> [!NOTE] +> [!IMPORTANT] +> We are actively restructuring our documentation to follow the [Diátaxis framework](https://diataxis.fr/) > -> We are actively restructuring our documentation to be more beginner friendly. +> 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. +> This also provides the benefit of using `:doc` in the `nix repl` to view reference documentation locally on the fly. -When writing new docs use **Progressive Disclosure** +For documentation only relevant for contributors, use Markdown files next to the source and regular code comments. -Start simple, pick up beginners. -Use **examples** first to show how to get something done. Keep **Explanation** lean. - -Use our [styleguide](./styleguide.md) for more in depth guidance on writing good documentation. - -This directory contains **guides** and **reference** documentation for Nixpkgs. - -Borrowing from [Diátaxis framework](https://diataxis.fr/) what suits our needs: - -**Guides** are task-oriented. They can be tutorial-style walkthroughs or how-to sections. -Explanations appear as prose after examples. - -**Reference** documentation is the specification of functions and attributes. - -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. - -See [Document structure](#document-structure) for a structural template. +> [!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/) @@ -65,11 +54,9 @@ Make sure that your local files aren't added to Git history by adding the follow /**/.direnv ``` -#### Live preview +#### `devmode` -Run [`devmode`](../pkgs/by-name/de/devmode/README.md) for a live preview while editing the manual: it rebuilds on every change and reloads the page in your browser automatically. - -Changes to the renderer 'pkgs/by-name/ni/nixos-render-docs' need a manual restart. Run: `devmode` again. +Use [`devmode`](../pkgs/by-name/de/devmode/README.md) for a live preview when editing the manual. ### Testing redirects @@ -222,62 +209,6 @@ You, as the writer of documentation, are still in charge of its content. **For prose style, see the [documentation styleguide](./styleguide.md).** -### Document structure - -Organize each chapter as guide sections first, then a single `## Reference` section. - -A well-structured chapter looks like this: - -````markdown -# Foo {#foo} - -`foo` builds Foo projects from a `foo.toml`. - -## Package a Foo application {#foo-packaging} - -:::{.example #ex-foo-packaging} - -# Package the hello app - -```nix -{ foo }: -buildFooPackage { - pname = "hello"; - version = "1.0"; -} -``` - -::: - -`buildFooPackage` needs `pname` and `version`. -Keep explanation short, and place it after the example. - -## Reference {#foo-reference} - -### `buildFooPackage` {#foo-buildFooPackage} - -Builds a Foo application from source. - -#### Inputs {#foo-buildFooPackage-inputs} - -`pname` (String) -: The program name. - -#### Examples {#foo-buildFooPackage-examples} - -See [](#ex-foo-packaging). -```` - -Examples live in one place: the guide owns them and the reference links to them. - -Guides introduce minimal working examples that are goal-oriented (typical usage). - -Reference may introduce additional examples that are unit-oriented. (minimal usage, edge-cases). -If the guide example is already sufficient, just link to it from the reference. - -Follow this structure strictly; to deviate, ping @NixOS/documentation-team. - - ### One sentence per line Put each sentence in its own line. @@ -353,15 +284,7 @@ Use the [admonition syntax](#admonitions) for callouts and examples. ### `callPackage`-compatible examples -Provide at least one example per function, in its doc-comment. - -Keep each example at the level it documents: - -- A **reference example** might sometimes live in a doc-comment and show function call shape. -- A **guide example** lives in a guide section and shows a complete task that may compose several functions. - -When the task is nothing more than the call itself, the guide example is enough. -The reference example links to the guide example. +Provide at least one example per function. Example code should be such that it can be passed to `pkgs.callPackage`. Instead of something like: diff --git a/doc/build-helpers.md b/doc/build-helpers.md index 8b38a79ceff4..f11deafdc24d 100644 --- a/doc/build-helpers.md +++ b/doc/build-helpers.md @@ -25,5 +25,6 @@ build-helpers/dev-shell-tools.chapter.md build-helpers/special.md build-helpers/images.md hooks/index.md +languages-frameworks/index.md packages/index.md ``` diff --git a/doc/build-helpers/dev-shell-tools.chapter.md b/doc/build-helpers/dev-shell-tools.chapter.md index 9de64474d218..2571380a3e06 100644 --- a/doc/build-helpers/dev-shell-tools.chapter.md +++ b/doc/build-helpers/dev-shell-tools.chapter.md @@ -2,7 +2,7 @@ The `nix-shell` command has popularized the concept of transient shell environments for development or testing purposes.