nixos/lib, doc: remove references to mdDoc (#300738) (ebde3065) · Commits · nix / nixpkgs

nixos/doc/manual/development/option-declarations.section.md

+8 −11

Original line number	Diff line number	Diff line
		@@ -12,7 +12,7 @@ looks like this:
		type = type specification;
		default = default value;
		example = example value;
		description = lib.mdDoc "Description for use in the NixOS manual.";
		description = "Description for use in the NixOS manual.";
		};
		};
		}
		@@ -58,12 +58,9 @@ The function `mkOption` accepts the following arguments.

		`description`

		: A textual description of the option, in [Nixpkgs-flavored Markdown](
		https://nixos.org/nixpkgs/manual/#sec-contributing-markup) format, that will be
		included in the NixOS manual. During the migration process from DocBook
		it is necessary to mark descriptions written in CommonMark with `lib.mdDoc`.
		The description may still be written in DocBook (without any marker), but this
		is discouraged and will be deprecated in the future.
		: A textual description of the option in [Nixpkgs-flavored Markdown](
		https://nixos.org/nixpkgs/manual/#sec-contributing-markup) format that will be
		included in the NixOS manual.

		## Utility functions for common option patterns {#sec-option-declarations-util}

		@@ -81,13 +78,13 @@ For example:
		::: {#ex-options-declarations-util-mkEnableOption-magic .example}
		### `mkEnableOption` usage
		```nix
		lib.mkEnableOption (lib.mdDoc "magic")
		lib.mkEnableOption "magic"
		# is like
		lib.mkOption {
		type = lib.types.bool;
		default = false;
		example = true;
		description = lib.mdDoc "Whether to enable magic.";
		description = "Whether to enable magic.";
		}
		```
		:::
		@@ -135,7 +132,7 @@ lib.mkOption {
		type = lib.types.package;
		default = pkgs.hello;
		defaultText = lib.literalExpression "pkgs.hello";
		description = lib.mdDoc "The hello package to use.";
		description = "The hello package to use.";
		}
		```
		:::
		@@ -153,7 +150,7 @@ lib.mkOption {
		default = pkgs.ghc;
		defaultText = lib.literalExpression "pkgs.ghc";
		example = lib.literalExpression "pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])";
		description = lib.mdDoc "The GHC package to use.";
		description = "The GHC package to use.";
		}
		```
		:::

nixos/lib/make-options-doc/default.nix

+1 −3

Original line number	Diff line number	Diff line
		@@ -117,9 +117,7 @@
		# deprecated since 23.11.
		# TODO remove in a while.
		, allowDocBook ? false
		# whether lib.mdDoc is required for descriptions to be read as markdown.
		# deprecated since 23.11.
		# TODO remove in a while.
		# TODO remove in a while (see https://github.com/NixOS/nixpkgs/issues/300735)
		, markdownByDefault ? true
		}:

nixos/lib/systemd-types.nix

+4 −5

Original line number	Diff line number	Diff line
		@@ -31,7 +31,6 @@ let
		;

		inherit (lib)
		mdDoc
		mkDefault
		mkDerivedConfig
		mkEnableOption
		@@ -81,11 +80,11 @@ rec {

		initrdContents = attrsOf (submodule ({ config, options, name, ... }: {
		options = {
		enable = mkEnableOption (mdDoc "copying of this file and symlinking it") // { default = true; };
		enable = (mkEnableOption "copying of this file and symlinking it") // { default = true; };

		target = mkOption {
		type = path;
		description = mdDoc ''
		description = ''
		Path of the symlink.
		'';
		default = name;
		@@ -94,12 +93,12 @@ rec {
		text = mkOption {
		default = null;
		type = nullOr lines;
		description = mdDoc "Text of the file.";
		description = "Text of the file.";
		};

		source = mkOption {
		type = path;
		description = mdDoc "Path of the source file.";
		description = "Path of the source file.";
		};
		};

nixos/lib/systemd-unit-options.nix

+54 −55

Original line number	Diff line number	Diff line
		@@ -17,7 +17,6 @@ let
		concatMap
		filterOverrides
		isList
		mdDoc
		mergeEqualOption
		mkIf
		mkMerge
		@@ -55,7 +54,7 @@ in rec {
		enable = mkOption {
		default = true;
		type = types.bool;
		description = mdDoc ''
		description = ''
		If set to false, this unit will be a symlink to
		/dev/null. This is primarily useful to prevent specific
		template instances
		@@ -69,7 +68,7 @@ in rec {
		overrideStrategy = mkOption {
		default = "asDropinIfExists";
		type = types.enum [ "asDropinIfExists" "asDropin" ];
		description = mdDoc ''
		description = ''
		Defines how unit configuration is provided for systemd:

		`asDropinIfExists` creates a unit file when no unit file is provided by the package
		@@ -85,7 +84,7 @@ in rec {
		requiredBy = mkOption {
		default = [];
		type = types.listOf unitNameType;
		description = mdDoc ''
		description = ''
		Units that require (i.e. depend on and need to go down with) this unit.
		As discussed in the `wantedBy` option description this also creates
		`.requires` symlinks automatically.
		@@ -95,7 +94,7 @@ in rec {
		upheldBy = mkOption {
		default = [];
		type = types.listOf unitNameType;
		description = mdDoc ''
		description = ''
		Keep this unit running as long as the listed units are running. This is a continuously
		enforced version of wantedBy.
		'';
		@@ -104,7 +103,7 @@ in rec {
		wantedBy = mkOption {
		default = [];
		type = types.listOf unitNameType;
		description = mdDoc ''
		description = ''
		Units that want (i.e. depend on) this unit. The default method for
		starting a unit by default at boot time is to set this option to
		`["multi-user.target"]` for system services. Likewise for user units
		@@ -122,7 +121,7 @@ in rec {
		aliases = mkOption {
		default = [];
		type = types.listOf unitNameType;
		description = mdDoc "Aliases of that unit.";
		description = "Aliases of that unit.";
		};

		};
		@@ -132,12 +131,12 @@ in rec {
		text = mkOption {
		type = types.nullOr types.str;
		default = null;
		description = mdDoc "Text of this systemd unit.";
		description = "Text of this systemd unit.";
		};

		unit = mkOption {
		internal = true;
		description = mdDoc "The generated unit.";
		description = "The generated unit.";
		};

		};
		@@ -148,19 +147,19 @@ in rec {
		description = mkOption {
		default = "";
		type = types.singleLineStr;
		description = mdDoc "Description of this unit used in systemd messages and progress indicators.";
		description = "Description of this unit used in systemd messages and progress indicators.";
		};

		documentation = mkOption {
		default = [];
		type = types.listOf types.str;
		description = mdDoc "A list of URIs referencing documentation for this unit or its configuration.";
		description = "A list of URIs referencing documentation for this unit or its configuration.";
		};

		requires = mkOption {
		default = [];
		type = types.listOf unitNameType;
		description = mdDoc ''
		description = ''
		Start the specified units when this unit is started, and stop
		this unit when the specified units are stopped or fail.
		'';
		@@ -169,7 +168,7 @@ in rec {
		wants = mkOption {
		default = [];
		type = types.listOf unitNameType;
		description = mdDoc ''
		description = ''
		Start the specified units when this unit is started.
		'';
		};
		@@ -177,7 +176,7 @@ in rec {
		upholds = mkOption {
		default = [];
		type = types.listOf unitNameType;
		description = mdDoc ''
		description = ''
		Keeps the specified running while this unit is running. A continuous version of `wants`.
		'';
		};
		@@ -185,7 +184,7 @@ in rec {
		after = mkOption {
		default = [];
		type = types.listOf unitNameType;
		description = mdDoc ''
		description = ''
		If the specified units are started at the same time as
		this unit, delay this unit until they have started.
		'';
		@@ -194,7 +193,7 @@ in rec {
		before = mkOption {
		default = [];
		type = types.listOf unitNameType;
		description = mdDoc ''
		description = ''
		If the specified units are started at the same time as
		this unit, delay them until this unit has started.
		'';
		@@ -203,7 +202,7 @@ in rec {
		bindsTo = mkOption {
		default = [];
		type = types.listOf unitNameType;
		description = mdDoc ''
		description = ''
		Like ‘requires’, but in addition, if the specified units
		unexpectedly disappear, this unit will be stopped as well.
		'';
		@@ -212,7 +211,7 @@ in rec {
		partOf = mkOption {
		default = [];
		type = types.listOf unitNameType;
		description = mdDoc ''
		description = ''
		If the specified units are stopped or restarted, then this
		unit is stopped or restarted as well.
		'';
		@@ -221,7 +220,7 @@ in rec {
		conflicts = mkOption {
		default = [];
		type = types.listOf unitNameType;
		description = mdDoc ''
		description = ''
		If the specified units are started, then this unit is stopped
		and vice versa.
		'';
		@@ -230,7 +229,7 @@ in rec {
		requisite = mkOption {
		default = [];
		type = types.listOf unitNameType;
		description = mdDoc ''
		description = ''
		Similar to requires. However if the units listed are not started,
		they will not be started and the transaction will fail.
		'';
		@@ -240,7 +239,7 @@ in rec {
		default = {};
		example = { RequiresMountsFor = "/data"; };
		type = types.attrsOf unitOption;
		description = mdDoc ''
		description = ''
		Each attribute in this set specifies an option in the
		`[Unit]` section of the unit. See
		{manpage}`systemd.unit(5)` for details.
		@@ -250,7 +249,7 @@ in rec {
		onFailure = mkOption {
		default = [];
		type = types.listOf unitNameType;
		description = mdDoc ''
		description = ''
		A list of one or more units that are activated when
		this unit enters the "failed" state.
		'';
		@@ -259,7 +258,7 @@ in rec {
		onSuccess = mkOption {
		default = [];
		type = types.listOf unitNameType;
		description = mdDoc ''
		description = ''
		A list of one or more units that are activated when
		this unit enters the "inactive" state.
		'';
		@@ -267,7 +266,7 @@ in rec {

		startLimitBurst = mkOption {
		type = types.int;
		description = mdDoc ''
		description = ''
		Configure unit start rate limiting. Units which are started
		more than startLimitBurst times within an interval time
		interval are not permitted to start any more.
		@@ -276,7 +275,7 @@ in rec {

		startLimitIntervalSec = mkOption {
		type = types.int;
		description = mdDoc ''
		description = ''
		Configure unit start rate limiting. Units which are started
		more than startLimitBurst times within an interval time
		interval are not permitted to start any more.
		@@ -295,7 +294,7 @@ in rec {
		restartTriggers = mkOption {
		default = [];
		type = types.listOf types.unspecified;
		description = mdDoc ''
		description = ''
		An arbitrary list of items such as derivations. If any item
		in the list changes between reconfigurations, the service will
		be restarted.
		@@ -305,7 +304,7 @@ in rec {
		reloadTriggers = mkOption {
		default = [];
		type = types.listOf unitOption;
		description = mdDoc ''
		description = ''
		An arbitrary list of items such as derivations. If any item
		in the list changes between reconfigurations, the service will
		be reloaded. If anything but a reload trigger changes in the
		@@ -323,13 +322,13 @@ in rec {
		default = {};
		type = with types; attrsOf (nullOr (oneOf [ str path package ]));
		example = { PATH = "/foo/bar/bin"; LANG = "nl_NL.UTF-8"; };
		description = mdDoc "Environment variables passed to the service's processes.";
		description = "Environment variables passed to the service's processes.";
		};

		path = mkOption {
		default = [];
		type = with types; listOf (oneOf [ package str ]);
		description = mdDoc ''
		description = ''
		Packages added to the service's {env}`PATH`
		environment variable. Both the {file}`bin`
		and {file}`sbin` subdirectories of each
		@@ -343,7 +342,7 @@ in rec {
		{ RestartSec = 5;
		};
		type = types.addCheck (types.attrsOf unitOption) checkService;
		description = mdDoc ''
		description = ''
		Each attribute in this set specifies an option in the
		`[Service]` section of the unit. See
		{manpage}`systemd.service(5)` for details.
		@@ -353,14 +352,14 @@ in rec {
		script = mkOption {
		type = types.lines;
		default = "";
		description = mdDoc "Shell commands executed as the service's main process.";
		description = "Shell commands executed as the service's main process.";
		};

		scriptArgs = mkOption {
		type = types.str;
		default = "";
		example = "%i";
		description = mdDoc ''
		description = ''
		Arguments passed to the main process script.
		Can contain specifiers (`%` placeholders expanded by systemd, see {manpage}`systemd.unit(5)`).
		'';
		@@ -369,7 +368,7 @@ in rec {
		preStart = mkOption {
		type = types.lines;
		default = "";
		description = mdDoc ''
		description = ''
		Shell commands executed before the service's main process
		is started.
		'';
		@@ -378,7 +377,7 @@ in rec {
		postStart = mkOption {
		type = types.lines;
		default = "";
		description = mdDoc ''
		description = ''
		Shell commands executed after the service's main process
		is started.
		'';
		@@ -387,7 +386,7 @@ in rec {
		reload = mkOption {
		type = types.lines;
		default = "";
		description = mdDoc ''
		description = ''
		Shell commands executed when the service's main process
		is reloaded.
		'';
		@@ -396,7 +395,7 @@ in rec {
		preStop = mkOption {
		type = types.lines;
		default = "";
		description = mdDoc ''
		description = ''
		Shell commands executed to stop the service.
		'';
		};
		@@ -404,7 +403,7 @@ in rec {
		postStop = mkOption {
		type = types.lines;
		default = "";
		description = mdDoc ''
		description = ''
		Shell commands executed after the service's main process
		has exited.
		'';
		@@ -413,7 +412,7 @@ in rec {
		jobScripts = mkOption {
		type = with types; coercedTo path singleton (listOf path);
		internal = true;
		description = mdDoc "A list of all job script derivations of this unit.";
		description = "A list of all job script derivations of this unit.";
		default = [];
		};

		@@ -458,7 +457,7 @@ in rec {
		restartIfChanged = mkOption {
		type = types.bool;
		default = true;
		description = mdDoc ''
		description = ''
		Whether the service should be restarted during a NixOS
		configuration switch if its definition has changed.
		'';
		@@ -467,7 +466,7 @@ in rec {
		reloadIfChanged = mkOption {
		type = types.bool;
		default = false;
		description = mdDoc ''
		description = ''
		Whether the service should be reloaded during a NixOS
		configuration switch if its definition has changed. If
		enabled, the value of {option}`restartIfChanged` is
		@@ -483,7 +482,7 @@ in rec {
		stopIfChanged = mkOption {
		type = types.bool;
		default = true;
		description = mdDoc ''
		description = ''
		If set, a changed unit is restarted by calling
		{command}`systemctl stop` in the old configuration,
		then {command}`systemctl start` in the new one.
		@@ -499,7 +498,7 @@ in rec {
		type = with types; either str (listOf str);
		default = [];
		example = "Sun 14:00:00";
		description = mdDoc ''
		description = ''
		Automatically start this unit at the given date/time, which
		must be in the format described in
		{manpage}`systemd.time(7)`. This is equivalent
		@@ -526,7 +525,7 @@ in rec {
		default = [];
		type = types.listOf types.str;
		example = [ "0.0.0.0:993" "/run/my-socket" ];
		description = mdDoc ''
		description = ''
		For each item in this list, a `ListenStream`
		option in the `[Socket]` section will be created.
		'';
		@@ -536,7 +535,7 @@ in rec {
		default = [];
		type = types.listOf types.str;
		example = [ "0.0.0.0:993" "/run/my-socket" ];
		description = mdDoc ''
		description = ''
		For each item in this list, a `ListenDatagram`
		option in the `[Socket]` section will be created.
		'';
		@@ -546,7 +545,7 @@ in rec {
		default = {};
		example = { ListenStream = "/run/my-socket"; };
		type = types.attrsOf unitOption;
		description = mdDoc ''
		description = ''
		Each attribute in this set specifies an option in the
		`[Socket]` section of the unit. See
		{manpage}`systemd.socket(5)` for details.
		@@ -578,7 +577,7 @@ in rec {
		default = {};
		example = { OnCalendar = "Sun 14:00:00"; Unit = "foo.service"; };
		type = types.attrsOf unitOption;
		description = mdDoc ''
		description = ''
		Each attribute in this set specifies an option in the
		`[Timer]` section of the unit. See
		{manpage}`systemd.timer(5)` and
		@@ -611,7 +610,7 @@ in rec {
		default = {};
		example = { PathChanged = "/some/path"; Unit = "changedpath.service"; };
		type = types.attrsOf unitOption;
		description = mdDoc ''
		description = ''
		Each attribute in this set specifies an option in the
		`[Path]` section of the unit. See
		{manpage}`systemd.path(5)` for details.
		@@ -642,13 +641,13 @@ in rec {
		what = mkOption {
		example = "/dev/sda1";
		type = types.str;
		description = mdDoc "Absolute path of device node, file or other resource. (Mandatory)";
		description = "Absolute path of device node, file or other resource. (Mandatory)";
		};

		where = mkOption {
		example = "/mnt";
		type = types.str;
		description = mdDoc ''
		description = ''
		Absolute path of a directory of the mount point.
		Will be created if it doesn't exist. (Mandatory)
		'';
		@@ -658,21 +657,21 @@ in rec {
		default = "";
		example = "ext4";
		type = types.str;
		description = mdDoc "File system type.";
		description = "File system type.";
		};

		options = mkOption {
		default = "";
		example = "noatime";
		type = types.commas;
		description = mdDoc "Options used to mount the file system.";
		description = "Options used to mount the file system.";
		};

		mountConfig = mkOption {
		default = {};
		example = { DirectoryMode = "0775"; };
		type = types.attrsOf unitOption;
		description = mdDoc ''
		description = ''
		Each attribute in this set specifies an option in the
		`[Mount]` section of the unit. See
		{manpage}`systemd.mount(5)` for details.
		@@ -702,7 +701,7 @@ in rec {
		where = mkOption {
		example = "/mnt";
		type = types.str;
		description = mdDoc ''
		description = ''
		Absolute path of a directory of the mount point.
		Will be created if it doesn't exist. (Mandatory)
		'';
		@@ -712,7 +711,7 @@ in rec {
		default = {};
		example = { DirectoryMode = "0775"; };
		type = types.attrsOf unitOption;
		description = mdDoc ''
		description = ''
		Each attribute in this set specifies an option in the
		`[Automount]` section of the unit. See
		{manpage}`systemd.automount(5)` for details.
		@@ -743,7 +742,7 @@ in rec {
		default = {};
		example = { MemoryMax = "2G"; };
		type = types.attrsOf unitOption;
		description = mdDoc ''
		description = ''
		Each attribute in this set specifies an option in the
		`[Slice]` section of the unit. See
		{manpage}`systemd.slice(5)` for details.

nixos/lib/testing/driver.nix

+10 −10

Original line number	Diff line number	Diff line
		{ config, lib, hostPkgs, ... }:
		let
		inherit (lib) mkOption types literalMD mdDoc;
		inherit (lib) mkOption types literalMD;

		# Reifies and correctly wraps the python test driver for
		# the respective qemu version and with or without ocr support
		@@ -104,13 +104,13 @@ in
		options = {

		driver = mkOption {
		description = mdDoc "Package containing a script that runs the test.";
		description = "Package containing a script that runs the test.";
		type = types.package;
		defaultText = literalMD "set by the test framework";
		};

		hostPkgs = mkOption {
		description = mdDoc "Nixpkgs attrset used outside the nodes.";
		description = "Nixpkgs attrset used outside the nodes.";
		type = types.raw;
		example = lib.literalExpression ''
		import nixpkgs { inherit system config overlays; }
		@@ -118,14 +118,14 @@ in
		};

		qemu.package = mkOption {
		description = mdDoc "Which qemu package to use for the virtualisation of [{option}`nodes`](#test-opt-nodes).";
		description = "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";
		};

		globalTimeout = mkOption {
		description = mdDoc ''
		description = ''
		A global timeout for the complete test, expressed in seconds.
		Beyond that timeout, every resource will be killed and released and the test will fail.

		@@ -137,7 +137,7 @@ in
		};

		enableOCR = mkOption {
		description = mdDoc ''
		description = ''
		Whether to enable Optical Character Recognition functionality for
		testing graphical programs. See [Machine objects](`ssec-machine-objects`).
		'';
		@@ -146,7 +146,7 @@ in
		};

		extraPythonPackages = mkOption {
		description = mdDoc ''
		description = ''
		Python packages to add to the test driver.

		The argument is a Python package set, similar to `pkgs.pythonPackages`.
		@@ -159,7 +159,7 @@ in
		};

		extraDriverArgs = mkOption {
		description = mdDoc ''
		description = ''
		Extra arguments to pass to the test driver.

		They become part of [{option}`driver`](#test-opt-driver) via `wrapProgram`.
		@@ -171,7 +171,7 @@ in
		skipLint = mkOption {
		type = types.bool;
		default = false;
		description = mdDoc ''
		description = ''
		Do not run the linters. This may speed up your iteration cycle, but it is not something you should commit.
		'';
		};
		@@ -179,7 +179,7 @@ in
		skipTypeCheck = mkOption {
		type = types.bool;
		default = false;
		description = mdDoc ''
		description = ''
		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`](#test-opt-testScript).