diff options
| -rwxr-xr-x | .github/workflows/compare-manuals.sh | 21 | ||||
| -rw-r--r-- | .github/workflows/manual-nixos.yml | 10 | ||||
| -rw-r--r-- | .github/workflows/manual-rendering.yml | 64 | ||||
| -rw-r--r-- | nixos/doc/manual/default.nix | 3 | ||||
| -rw-r--r-- | nixos/doc/manual/release-notes/rl-2311.section.md | 2 | ||||
| -rw-r--r-- | nixos/lib/make-options-doc/default.nix | 6 | ||||
| -rw-r--r-- | nixos/modules/misc/documentation.nix | 22 |
7 files changed, 14 insertions, 114 deletions
diff --git a/.github/workflows/compare-manuals.sh b/.github/workflows/compare-manuals.sh deleted file mode 100755 index b2cc68c7831..00000000000 --- a/.github/workflows/compare-manuals.sh +++ /dev/null @@ -1,21 +0,0 @@ -#!/usr/bin/env nix-shell -#! nix-shell -i bash -p html-tidy - -set -euo pipefail -shopt -s inherit_errexit - -normalize() { - tidy \ - --anchor-as-name no \ - --coerce-endtags no \ - --escape-scripts no \ - --fix-backslash no \ - --fix-style-tags no \ - --fix-uri no \ - --indent yes \ - --wrap 0 \ - < "$1" \ - 2> /dev/null -} - -diff -U3 <(normalize "$1") <(normalize "$2") diff --git a/.github/workflows/manual-nixos.yml b/.github/workflows/manual-nixos.yml index 30cecf607d1..2ada5832a7d 100644 --- a/.github/workflows/manual-nixos.yml +++ b/.github/workflows/manual-nixos.yml @@ -27,13 +27,5 @@ jobs: # This cache is for the nixpkgs repo checks and should not be trusted or used elsewhere. name: nixpkgs-ci signingKey: '${{ secrets.CACHIX_SIGNING_KEY }}' - - name: Building NixOS manual with DocBook options + - name: Building NixOS manual run: NIX_PATH=nixpkgs=$(pwd) nix-build --option restrict-eval true nixos/release.nix -A manual.x86_64-linux - - name: Building NixOS manual with Markdown options - run: | - export NIX_PATH=nixpkgs=$(pwd) - nix-build \ - --option restrict-eval true \ - --arg configuration '{ documentation.nixos.options.allowDocBook = false; }' \ - nixos/release.nix \ - -A manual.x86_64-linux diff --git a/.github/workflows/manual-rendering.yml b/.github/workflows/manual-rendering.yml deleted file mode 100644 index dbaea583ef7..00000000000 --- a/.github/workflows/manual-rendering.yml +++ /dev/null @@ -1,64 +0,0 @@ -name: "Check NixOS Manual DocBook rendering against MD rendering" - - -on: - schedule: - # * is a special character in YAML so you have to quote this string - # Check every 24 hours - - cron: '0 0 * * *' - -permissions: - contents: read - -jobs: - check-rendering-equivalence: - permissions: - pull-requests: write # for peter-evans/create-or-update-comment to create or update comment - if: github.repository_owner == 'NixOS' - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: cachix/install-nix-action@v21 - with: - # explicitly enable sandbox - extra_nix_config: sandbox = true - - uses: cachix/cachix-action@v12 - with: - # This cache is for the nixpkgs repo checks and should not be trusted or used elsewhere. - name: nixpkgs-ci - signingKey: '${{ secrets.CACHIX_SIGNING_KEY }}' - - - name: Build DocBook and MD manuals - run: | - export NIX_PATH=nixpkgs=$(pwd) - nix-build \ - --option restrict-eval true \ - -o docbook nixos/release.nix \ - -A manual.x86_64-linux - nix-build \ - --option restrict-eval true \ - --arg configuration '{ documentation.nixos.options.allowDocBook = false; }' \ - -o md nixos/release.nix \ - -A manual.x86_64-linux - - - name: Compare DocBook and MD manuals - id: check - run: | - export NIX_PATH=nixpkgs=$(pwd) - .github/workflows/compare-manuals.sh \ - docbook/share/doc/nixos/options.html \ - md/share/doc/nixos/options.html - - # if the manual can't be built we don't want to notify anyone. - # while this may temporarily hide rendering failures it will be a lot - # less noisy until all nixpkgs pull requests have stopped using - # docbook for option docs. - - name: Comment on failure - uses: peter-evans/create-or-update-comment@v3 - if: ${{ failure() && steps.check.conclusion == 'failure' }} - with: - issue-number: 189318 - body: | - Markdown and DocBook manuals do not agree. - - Check https://github.com/NixOS/nixpkgs/actions/runs/${{ github.run_id }} for details. diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix index 3052b353ee7..782275b382c 100644 --- a/nixos/doc/manual/default.nix +++ b/nixos/doc/manual/default.nix @@ -6,10 +6,11 @@ , extraSources ? [] , baseOptionsJSON ? null , warningsAreErrors ? true -, allowDocBook ? true +, allowDocBook ? false , prefix ? ../../.. }: +assert ! allowDocBook; with pkgs; let diff --git a/nixos/doc/manual/release-notes/rl-2311.section.md b/nixos/doc/manual/release-notes/rl-2311.section.md index a86961de671..700987db224 100644 --- a/nixos/doc/manual/release-notes/rl-2311.section.md +++ b/nixos/doc/manual/release-notes/rl-2311.section.md @@ -44,4 +44,6 @@ - A new option was added to the virtualisation module that enables specifying explicitly named network interfaces in QEMU VMs. The existing `virtualisation.vlans` is still supported for cases where the name of the network interface is irrelevant. +- DocBook option documentation is no longer supported, all module documentation now uses markdown. + - `services.nginx` gained a `defaultListen` option at server-level with support for PROXY protocol listeners, also `proxyProtocol` is now exposed in `services.nginx.virtualHosts.<name>.listen` option. It is now possible to run PROXY listeners and non-PROXY listeners at a server-level, see [#213510](https://github.com/NixOS/nixpkgs/pull/213510/) for more details. diff --git a/nixos/lib/make-options-doc/default.nix b/nixos/lib/make-options-doc/default.nix index a2385582a01..e4d9a6ebcc7 100644 --- a/nixos/lib/make-options-doc/default.nix +++ b/nixos/lib/make-options-doc/default.nix @@ -39,12 +39,16 @@ # allow docbook option docs if `true`. only markdown documentation is allowed when set to # `false`, and a different renderer may be used with different bugs and performance # characteristics but (hopefully) indistinguishable output. -, allowDocBook ? true +# deprecated since 23.11. +# TODO remove in a while. +, allowDocBook ? false # whether lib.mdDoc is required for descriptions to be read as markdown. # !!! when this is eventually flipped to true, `lib.doRename` should also default to emitting Markdown , markdownByDefault ? false }: +assert ! allowDocBook; + let rawOpts = lib.optionAttrSetToDocList options; transformedOpts = map transformOptions rawOpts; diff --git a/nixos/modules/misc/documentation.nix b/nixos/modules/misc/documentation.nix index 31486a2216a..e6a56a8cdf2 100644 --- a/nixos/modules/misc/documentation.nix +++ b/nixos/modules/misc/documentation.nix @@ -107,7 +107,7 @@ let } >&2 ''; - inherit (cfg.nixos.options) warningsAreErrors allowDocBook; + inherit (cfg.nixos.options) warningsAreErrors; }; @@ -160,6 +160,9 @@ in (mkRenamedOptionModule [ "programs" "info" "enable" ] [ "documentation" "info" "enable" ]) (mkRenamedOptionModule [ "programs" "man" "enable" ] [ "documentation" "man" "enable" ]) (mkRenamedOptionModule [ "services" "nixosManual" "enable" ] [ "documentation" "nixos" "enable" ]) + (mkRemovedOptionModule + [ "documentation" "nixos" "options" "allowDocBook" ] + "DocBook option documentation is no longer supported") ]; options = { @@ -264,23 +267,6 @@ in ''; }; - nixos.options.allowDocBook = mkOption { - type = types.bool; - default = true; - description = lib.mdDoc '' - Whether to allow DocBook option docs. When set to `false` all option using - DocBook documentation will cause a manual build error; additionally a new - renderer may be used. - - ::: {.note} - The `false` setting for this option is not yet fully supported. While it - should work fine and produce the same output as the previous toolchain - using DocBook it may not work in all circumstances. Whether markdown option - documentation is allowed is independent of this option. - ::: - ''; - }; - nixos.options.warningsAreErrors = mkOption { type = types.bool; default = true; |