diff options
author | pennae <github@quasiparticle.net> | 2023-06-11 19:29:32 +0200 |
---|---|---|
committer | pennae <github@quasiparticle.net> | 2023-06-13 16:56:30 +0200 |
commit | 0997ae1903b0f18cd9e43e4a65ffdd8f1e1ff285 (patch) | |
tree | 0239331544240803f0566bd54b5b58a9758db9da | |
parent | 96ce8d59649f20c21b01f146bcd6b37aa14cd59e (diff) | |
download | nixpkgs-0997ae1903b0f18cd9e43e4a65ffdd8f1e1ff285.tar nixpkgs-0997ae1903b0f18cd9e43e4a65ffdd8f1e1ff285.tar.gz nixpkgs-0997ae1903b0f18cd9e43e4a65ffdd8f1e1ff285.tar.bz2 nixpkgs-0997ae1903b0f18cd9e43e4a65ffdd8f1e1ff285.tar.lz nixpkgs-0997ae1903b0f18cd9e43e4a65ffdd8f1e1ff285.tar.xz nixpkgs-0997ae1903b0f18cd9e43e4a65ffdd8f1e1ff285.tar.zst nixpkgs-0997ae1903b0f18cd9e43e4a65ffdd8f1e1ff285.zip |
nixos/manual: disallow docbook option docs
it's been long in the making, and with 23.05 out we can finally disable docbook option docs and default to markdown instead. this brings a massive speed boost in manual and manpage builds, so much so that we may consider enabling user module documentation by default. we don't remove the docbook support code entirely yet because it's a lot all over, and probably better removed in multiple separate changes.
-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; |