From 91879ce1604060e3b91d275f7686b98d2357c9a6 Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Thu, 29 Sep 2022 12:34:06 +0200 Subject: [PATCH 1/2] make-options-doc: Make optionIdPrefix configurable ("opt-") --- nixos/lib/make-options-doc/default.nix | 3 +++ nixos/lib/make-options-doc/options-to-docbook.xsl | 3 ++- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/nixos/lib/make-options-doc/default.nix b/nixos/lib/make-options-doc/default.nix index 43dbff0e68dd..6a1bb868c20d 100644 --- a/nixos/lib/make-options-doc/default.nix +++ b/nixos/lib/make-options-doc/default.nix @@ -26,6 +26,8 @@ # If you include more than one option list into a document, you need to # provide different ids. , variablelistId ? "configuration-variable-list" + # Strig to prefix to the option XML/HTML id attributes. +, optionIdPrefix ? "opt-" , revision ? "" # Specify revision for the options # a set of options the docs we are generating will be merged into, as if by recursiveUpdate. # used to split the options doc build into a static part (nixos/modules) and a dynamic part @@ -183,6 +185,7 @@ in rec { --stringparam documentType '${documentType}' \ --stringparam revision '${revision}' \ --stringparam variablelistId '${variablelistId}' \ + --stringparam optionIdPrefix '${optionIdPrefix}' \ -o intermediate.xml ${./options-to-docbook.xsl} sorted.xml ${pkgs.libxslt.bin}/bin/xsltproc \ -o "$out" ${./postprocess-option-descriptions.xsl} intermediate.xml diff --git a/nixos/lib/make-options-doc/options-to-docbook.xsl b/nixos/lib/make-options-doc/options-to-docbook.xsl index 978d5e2468a8..d5b921b1dedb 100644 --- a/nixos/lib/make-options-doc/options-to-docbook.xsl +++ b/nixos/lib/make-options-doc/options-to-docbook.xsl @@ -15,6 +15,7 @@ + @@ -36,7 +37,7 @@ .driver` attribute instead, and call it with the flag `result/bin/nixos-test-driver --interactive`. diff --git a/nixos/doc/manual/development/writing-nixos-tests.section.md b/nixos/doc/manual/development/writing-nixos-tests.section.md index 99704ec3c141..2efe52b9883c 100644 --- a/nixos/doc/manual/development/writing-nixos-tests.section.md +++ b/nixos/doc/manual/development/writing-nixos-tests.section.md @@ -22,12 +22,12 @@ A NixOS test is a module that has the following structure: ``` We refer to the whole test above as a test module, whereas the values -in [`nodes.`](#opt-nodes) are NixOS modules themselves. +in [`nodes.`](#test-opt-nodes) are NixOS modules themselves. -The option [`testScript`](#opt-testScript) is a piece of Python code that executes the +The option [`testScript`](#test-opt-testScript) is a piece of Python code that executes the test (described below). During the test, it will start one or more virtual machines, the configuration of which is described by -the option [`nodes`](#opt-nodes). +the option [`nodes`](#test-opt-nodes). An example of a single-node test is [`login.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix). @@ -171,7 +171,7 @@ The following methods are available on machine objects: least one will be returned. ::: {.note} - This requires [`enableOCR`](#opt-enableOCR) to be set to `true`. + This requires [`enableOCR`](#test-opt-enableOCR) to be set to `true`. ::: `get_screen_text` @@ -180,7 +180,7 @@ The following methods are available on machine objects: machine\'s screen using optical character recognition. ::: {.note} - This requires [`enableOCR`](#opt-enableOCR) to be set to `true`. + This requires [`enableOCR`](#test-opt-enableOCR) to be set to `true`. ::: `send_monitor_command` @@ -291,7 +291,7 @@ The following methods are available on machine objects: `get_screen_text` and `get_screen_text_variants`). ::: {.note} - This requires [`enableOCR`](#opt-enableOCR) to be set to `true`. + This requires [`enableOCR`](#test-opt-enableOCR) to be set to `true`. ::: `wait_for_console_text` diff --git a/nixos/doc/manual/from_md/development/running-nixos-tests-interactively.section.xml b/nixos/doc/manual/from_md/development/running-nixos-tests-interactively.section.xml index 35d9bbd1c1fe..16db709f8b91 100644 --- a/nixos/doc/manual/from_md/development/running-nixos-tests-interactively.section.xml +++ b/nixos/doc/manual/from_md/development/running-nixos-tests-interactively.section.xml @@ -44,14 +44,14 @@ $ ./result/bin/nixos-test-driver --keep-vm-state The .driverInteractive attribute combines the regular test configuration with definitions from the - interactive + interactive submodule. This gives you a more usable, graphical, but slightly different configuration. You can add your own interactive-only test configuration by adding extra configuration to the - interactive + interactive submodule. diff --git a/nixos/doc/manual/from_md/development/writing-nixos-tests.section.xml b/nixos/doc/manual/from_md/development/writing-nixos-tests.section.xml index 32f5fdb77f50..4db196273dad 100644 --- a/nixos/doc/manual/from_md/development/writing-nixos-tests.section.xml +++ b/nixos/doc/manual/from_md/development/writing-nixos-tests.section.xml @@ -24,16 +24,16 @@ We refer to the whole test above as a test module, whereas the values in - nodes.<name> + nodes.<name> are NixOS modules themselves. The option - testScript + testScript is a piece of Python code that executes the test (described below). During the test, it will start one or more virtual machines, the configuration of which is described by the option - nodes. + nodes. An example of a single-node test is @@ -263,7 +263,7 @@ start_all() This requires - enableOCR + enableOCR to be set to true. @@ -281,7 +281,7 @@ start_all() This requires - enableOCR + enableOCR to be set to true. @@ -522,7 +522,7 @@ start_all() This requires - enableOCR + enableOCR to be set to true. diff --git a/nixos/lib/testing/driver.nix b/nixos/lib/testing/driver.nix index 04e99f9e21d6..fb181c1d7e9a 100644 --- a/nixos/lib/testing/driver.nix +++ b/nixos/lib/testing/driver.nix @@ -120,7 +120,7 @@ in }; qemu.package = mkOption { - description = mdDoc "Which qemu package to use for the virtualisation of [{option}`nodes`](#opt-nodes)."; + description = mdDoc "Which qemu package to use for the virtualisation of [{option}`nodes`](#test-opt-nodes)."; type = types.package; default = hostPkgs.qemu_test; defaultText = "hostPkgs.qemu_test"; @@ -152,7 +152,7 @@ in description = mdDoc '' Extra arguments to pass to the test driver. - They become part of [{option}`driver`](#opt-driver) via `wrapProgram`. + They become part of [{option}`driver`](#test-opt-driver) via `wrapProgram`. ''; type = types.listOf types.str; default = []; @@ -172,7 +172,7 @@ in description = mdDoc '' Disable type checking. This must not be enabled for new NixOS tests. - This may speed up your iteration cycle, unless you're working on the [{option}`testScript`](#opt-testScript). + This may speed up your iteration cycle, unless you're working on the [{option}`testScript`](#test-opt-testScript). ''; }; }; diff --git a/nixos/lib/testing/meta.nix b/nixos/lib/testing/meta.nix index 4d8b0e0f1c43..65754fe3c541 100644 --- a/nixos/lib/testing/meta.nix +++ b/nixos/lib/testing/meta.nix @@ -24,14 +24,14 @@ in type = types.nullOr types.int; default = null; # NOTE: null values are filtered out by `meta`. description = mdDoc '' - The [{option}`test`](#opt-test)'s [`meta.timeout`](https://nixos.org/manual/nixpkgs/stable/#var-meta-timeout) in seconds. + The [{option}`test`](#test-opt-test)'s [`meta.timeout`](https://nixos.org/manual/nixpkgs/stable/#var-meta-timeout) in seconds. ''; }; broken = lib.mkOption { type = types.bool; default = false; description = mdDoc '' - Sets the [`meta.broken`](https://nixos.org/manual/nixpkgs/stable/#var-meta-broken) attribute on the [{option}`test`](#opt-test) derivation. + Sets the [`meta.broken`](https://nixos.org/manual/nixpkgs/stable/#var-meta-broken) attribute on the [{option}`test`](#test-opt-test) derivation. ''; }; }; diff --git a/nixos/lib/testing/name.nix b/nixos/lib/testing/name.nix index a54622e139bf..0af593169eec 100644 --- a/nixos/lib/testing/name.nix +++ b/nixos/lib/testing/name.nix @@ -7,7 +7,7 @@ in description = mdDoc '' The name of the test. - This is used in the derivation names of the [{option}`driver`](#opt-driver) and [{option}`test`](#opt-test) runner. + This is used in the derivation names of the [{option}`driver`](#test-opt-driver) and [{option}`test`](#test-opt-test) runner. ''; type = types.str; }; diff --git a/nixos/lib/testing/nodes.nix b/nixos/lib/testing/nodes.nix index 765af2878dfe..0395238cbaae 100644 --- a/nixos/lib/testing/nodes.nix +++ b/nixos/lib/testing/nodes.nix @@ -44,7 +44,7 @@ in description = mdDoc '' An attribute set of NixOS configuration modules. - The configurations are augmented by the [`defaults`](#opt-defaults) option. + The configurations are augmented by the [`defaults`](#test-opt-defaults) option. They are assigned network addresses according to the `nixos/lib/testing/network.nix` module. @@ -54,7 +54,7 @@ in defaults = mkOption { description = mdDoc '' - NixOS configuration that is applied to all [{option}`nodes`](#opt-nodes). + NixOS configuration that is applied to all [{option}`nodes`](#test-opt-nodes). ''; type = types.deferredModule; default = { }; @@ -62,7 +62,7 @@ in extraBaseModules = mkOption { description = mdDoc '' - NixOS configuration that, like [{option}`defaults`](#opt-defaults), is applied to all [{option}`nodes`](#opt-nodes) and can not be undone with [`specialisation..inheritParentConfig`](https://search.nixos.org/options?show=specialisation.%3Cname%3E.inheritParentConfig&from=0&size=50&sort=relevance&type=packages&query=specialisation). + NixOS configuration that, like [{option}`defaults`](#test-opt-defaults), is applied to all [{option}`nodes`](#test-opt-nodes) and can not be undone with [`specialisation..inheritParentConfig`](https://search.nixos.org/options?show=specialisation.%3Cname%3E.inheritParentConfig&from=0&size=50&sort=relevance&type=packages&query=specialisation). ''; type = types.deferredModule; default = { }; @@ -82,7 +82,7 @@ in type = types.bool; default = false; description = mdDoc '' - Enable to configure all [{option}`nodes`](#opt-nodes) to run with a minimal kernel. + Enable to configure all [{option}`nodes`](#test-opt-nodes) to run with a minimal kernel. ''; };