Merge master into staging-next

Note that these conventions are about the **structure** of the manual (and its source files), not about the content that goes in it.

You, as the writer of documentation, are still in charge of its content.

- Put each sentence in its own line.

### One sentence per line

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.

- Use the [admonition syntax](#admonitions) for callouts and examples.

### Callouts and examples

Use the [admonition syntax](#admonitions) for callouts and examples.

### Provide self-contained examples

- Provide at least one example per function, and make examples self-contained.

Provide at least one example per function, and make examples self-contained.

This is easier to understand for beginners.

It also helps with testing that it actually works – especially once we introduce automation.

}

```

- When showing inputs/outputs of any [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop), such as a shell or the Nix REPL, use a format as you'd see in the REPL, while trying to visually separate inputs from outputs.

### REPLs

When showing inputs/outputs of any [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop), such as a shell or the Nix REPL, use a format as you'd see in the REPL, while trying to visually separate inputs from outputs.

This means that for a shell, you should use a format like the following:

```shell

$ nix-build -A hello '<nixpkgs>' \

```

Note how the input is preceded by `nix-repl>` and the output is provided as you'd see on the Nix REPL.

- When documenting functions or anything that has inputs/outputs and example usage, use nested headings to clearly separate inputs, outputs, and examples.

### Headings for inputs, outputs and examples

When documenting functions or anything that has inputs/outputs and example usage, use nested headings to clearly separate inputs, outputs, and examples.

Keep examples as the last nested heading, and link to the examples wherever applicable in the documentation.

The purpose of this convention is to provide a familiar structure for navigating the manual, so any reader can expect to find content related to inputs in an "inputs" heading, examples in an "examples" heading, and so on.

:::

```

- Use [definition lists](#definition-lists) to document function arguments, and the attributes of such arguments as well as their [types](https://nixos.org/manual/nix/stable/language/values).

### Function arguments

Use [definition lists](#definition-lists) to document function arguments, and the attributes of such arguments as well as their [types](https://nixos.org/manual/nix/stable/language/values).

For example:

```markdown

- `nodePackages.coc-python` was dropped, as [its upstream is unmaintained](https://github.com/neoclide/coc-python). The associated `vimPlugins.coc-python` was also dropped.

  The upstream project recommends using `coc-pyright` or `coc-jedi` as replacements.

- `forgejo` has been upgraded from version 7.0 to version 9.0, see the release notes for [8.0](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/RELEASE-NOTES.md#8-0-0) and [9.0](https://codeberg.org/forgejo/forgejo/milestone/7235).

- `services.forgejo.mailerPasswordFile` has been deprecated by the drop-in replacement `services.forgejo.secrets.mailer.PASSWD`,

  which is part of the new free-form `services.forgejo.secrets` option.

  `services.forgejo.secrets` is a small wrapper over systemd's `LoadCredential=`. It has the same structure (sections/keys) as

  `services.forgejo.settings` but takes file paths that will be read before service startup instead of some plaintext value.

  `services.forgejo.package` now defaults to `forgejo-lts`, the Long Term Support version of Forgejo.

- `forgejo` and `forgejo-lts` no longer support the opt-in feature [PAM (Pluggable Authentication Module)](https://forgejo.org/docs/latest/user/authentication/#pam-pluggable-authentication-module).

    };

  };

  power-pkg = config.boot.kernelPackages.system76-power;

  power-pkg = pkgs.system76-power;

  powerConfig = mkIf cfg.power-daemon.enable {

    # Make system76-power usable by root from the command line.

    environment.systemPackages = [ power-pkg ];

      package = mkOption {

        type = types.package;

        default = config.boot.kernelPackages.system76-scheduler;

        defaultText = literalExpression "config.boot.kernelPackages.system76-scheduler";

        default = pkgs.system76-scheduler;

        defaultText = literalExpression "pkgs.system76-scheduler";

        description = "Which System76-Scheduler package to use.";

      };

        # No custom settings: just use stock configuration with a fix for Pipewire

        "system76-scheduler/config.kdl".source = "${cfg.package}/data/config.kdl";

        "system76-scheduler/process-scheduler/00-dist.kdl".source = "${cfg.package}/data/pop_os.kdl";

        "system76-scheduler/process-scheduler/01-fix-pipewire-paths.kdl".source = ../../../../pkgs/os-specific/linux/system76-scheduler/01-fix-pipewire-paths.kdl;

        "system76-scheduler/process-scheduler/01-fix-pipewire-paths.kdl".source = ../../../../pkgs/by-name/sy/system76-scheduler/01-fix-pipewire-paths.kdl;

      })

      (let

      ${pkgs.system} = "${nixVersions.latest}";

    }'';

  inputDrv = import ../.. {

    configuration = {

      imports = [ nixos-module ];

      nix.package = nixVersions.latest;

      boot.isContainer = true;

      users.users.alice.isNormalUser = true;

    };

    system = pkgs.system;

  };

  nixos-module = builtins.toFile "nixos-module.nix" ''

    { lib, pkgs, modulesPath, ... }:

    {

    nix.package = nixVersions.stable;

    system.extraDependencies = [

      fallback-paths-external

      inputDrv.system

    ];

    specialisation.newer-nix.configuration = {

      nix.package = lib.mkForce nixVersions.latest;

      users.users.alice.isNormalUser = true;

    };

  };

  testScript = ''

    with subtest("upgrade-via-switch-to-configuration"):

        # not using nixos-rebuild due to nix-instantiate being called and forcing all drv's to be rebuilt

        print(machine.succeed("${inputDrv.system.outPath}/bin/switch-to-configuration switch"))

        print(machine.succeed("/run/current-system/specialisation/newer-nix/bin/switch-to-configuration switch"))

        result = machine.succeed("nix --version")

        print(result)