gador/nixpkgs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

treewide: automatically md-convert option descriptions

Browse Source 
the conversion procedure is simple:

 - find all things that look like options, ie calls to either `mkOption`
   or `lib.mkOption` that take an attrset. remember the attrset as the
   option
 - for all options, find a `description` attribute who's value is not a
   call to `mdDoc` or `lib.mdDoc`
 - textually convert the entire value of the attribute to MD with a few
   simple regexes (the set from mdize-module.sh)
 - if the change produced a change in the manual output, discard
 - if the change kept the manual unchanged, add some text to the
   description to make sure we've actually found an option. if the
   manual changes this time, keep the converted description

this procedure converts 80% of nixos options to markdown. around 2000
options remain to be inspected, but most of those fail the "does not
change the manual output check": currently the MD conversion process
does not faithfully convert docbook tags like <code> and <package>, so
any option using such tags will not be converted at all.
This commit is contained in:
pennae
2022-07-28 23:19:15 +02:00
parent 52b0ad17e3
commit 2e751c0772
1050 changed files with 9605 additions and 9605 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
nixos/modules/services/monitoring/prometheus/alertmanager.nix
View File

@@ -46,7 +46,7 @@ in {
type = types.package;
default = pkgs.prometheus-alertmanager;
defaultText = literalExpression "pkgs.alertmanager";
description = ''
description = lib.mdDoc ''
Package that should be used for alertmanager.
'';
};
@@ -54,7 +54,7 @@ in {
configuration = mkOption {
type = types.nullOr types.attrs;
default = null;
description = ''
description = lib.mdDoc ''
Alertmanager configuration as nix attribute set.
'';
};
@@ -62,7 +62,7 @@ in {
configText = mkOption {
type = types.nullOr types.lines;
default = null;
description = ''
description = lib.mdDoc ''
Alertmanager configuration as YAML text. If non-null, this option
defines the text that is written to alertmanager.yml. If null, the
contents of alertmanager.yml is generated from the structured config
@@ -73,7 +73,7 @@ in {
logFormat = mkOption {
type = types.nullOr types.str;
default = null;
description = ''
description = lib.mdDoc ''
If set use a syslog logger or JSON logging.
'';
};
@@ -81,7 +81,7 @@ in {
logLevel = mkOption {
type = types.enum ["debug" "info" "warn" "error" "fatal"];
default = "warn";
description = ''
description = lib.mdDoc ''
Only log messages with the given severity or above.
'';
};
@@ -89,7 +89,7 @@ in {
webExternalUrl = mkOption {
type = types.nullOr types.str;
default = null;
description = ''
description = lib.mdDoc ''
The URL under which Alertmanager is externally reachable (for example, if Alertmanager is served via a reverse proxy).
Used for generating relative and absolute links back to Alertmanager itself.
If the URL has a path portion, it will be used to prefix all HTTP endoints served by Alertmanager.
@@ -100,7 +100,7 @@ in {
listenAddress = mkOption {
type = types.str;
default = "";
description = ''
description = lib.mdDoc ''
Address to listen on for the web interface and API. Empty string will listen on all interfaces.
"localhost" will listen on 127.0.0.1 (but not ::1).
'';
@@ -109,7 +109,7 @@ in {
port = mkOption {
type = types.int;
default = 9093;
description = ''
description = lib.mdDoc ''
Port to listen on for the web interface and API.
'';
};
@@ -117,7 +117,7 @@ in {
openFirewall = mkOption {
type = types.bool;
default = false;
description = ''
description = lib.mdDoc ''
Open port in firewall for incoming connections.
'';
};
@@ -125,7 +125,7 @@ in {
clusterPeers = mkOption {
type = types.listOf types.str;
default = [];
description = ''
description = lib.mdDoc ''
Initial peers for HA cluster.
'';
};
@@ -133,7 +133,7 @@ in {
extraFlags = mkOption {
type = types.listOf types.str;
default = [];
description = ''
description = lib.mdDoc ''
Extra commandline options when launching the Alertmanager.
'';
};
@@ -142,11 +142,11 @@ in {
type = types.nullOr types.path;
default = null;
example = "/root/alertmanager.env";
description = ''
description = lib.mdDoc ''
File to load as environment file. Environment variables
from this file will be interpolated into the config file
using envsubst with this syntax:
<literal>$ENVIRONMENT ''${VARIABLE}</literal>
`$ENVIRONMENT ''${VARIABLE}`
'';
};
};

116
nixos/modules/services/monitoring/prometheus/default.nix
View File

@@ -184,7 +184,7 @@ let
options = {
username = mkOption {
type = types.str;
description = ''
description = lib.mdDoc ''
HTTP username
'';
};
@@ -257,7 +257,7 @@ let
};
job_name = mkOption {
type = types.str;
description = ''
description = lib.mdDoc ''
The job name assigned to scraped metrics by default.
'';
};
@@ -513,7 +513,7 @@ let
subscription_id = mkOption {
type = types.str;
description = ''
description = lib.mdDoc ''
The subscription ID.
'';
};
@@ -618,7 +618,7 @@ let
mkDockerSdConfigModule = extraOptions: mkSdConfigModule ({
host = mkOption {
type = types.str;
description = ''
description = lib.mdDoc ''
Address of the Docker daemon.
'';
};
@@ -675,7 +675,7 @@ let
options = {
names = mkOption {
type = types.listOf types.str;
description = ''
description = lib.mdDoc ''
A list of DNS SRV record names to be queried.
'';
};
@@ -698,7 +698,7 @@ let
options = {
region = mkOption {
type = types.str;
description = ''
description = lib.mdDoc ''
The AWS Region. If blank, the region from the instance metadata is used.
'';
};
@@ -762,7 +762,7 @@ let
promTypes.eureka_sd_config = mkSdConfigModule {
server = mkOption {
type = types.str;
description = ''
description = lib.mdDoc ''
The URL to connect to the Eureka server.
'';
};
@@ -772,7 +772,7 @@ let
options = {
files = mkOption {
type = types.listOf types.str;
description = ''
description = lib.mdDoc ''
Patterns for files from which target groups are extracted. Refer
to the Prometheus documentation for permitted filename patterns
and formats.
@@ -791,14 +791,14 @@ let
# required configuration values for `gce_sd_config`.
project = mkOption {
type = types.str;
description = ''
description = lib.mdDoc ''
The GCP Project.
'';
};
zone = mkOption {
type = types.str;
description = ''
description = lib.mdDoc ''
The zone of the scrape targets. If you need multiple zones use multiple
gce_sd_configs.
'';
@@ -833,9 +833,9 @@ let
promTypes.hetzner_sd_config = mkSdConfigModule {
role = mkOption {
type = types.enum [ "robot" "hcloud" ];
description = ''
description = lib.mdDoc ''
The Hetzner role of entities that should be discovered.
One of <literal>robot</literal> or <literal>hcloud</literal>.
One of `robot` or `hcloud`.
'';
};
@@ -852,7 +852,7 @@ let
options = {
url = mkOption {
type = types.str;
description = ''
description = lib.mdDoc ''
URL from which the targets are fetched.
'';
};
@@ -889,7 +889,7 @@ let
role = mkOption {
type = types.enum [ "endpoints" "service" "pod" "node" "ingress" ];
description = ''
description = lib.mdDoc ''
The Kubernetes role of entities that should be discovered.
One of endpoints, service, pod, node, or ingress.
'';
@@ -954,7 +954,7 @@ let
promTypes.kuma_sd_config = mkSdConfigModule {
server = mkOption {
type = types.str;
description = ''
description = lib.mdDoc ''
Address of the Kuma Control Plane's MADS xDS server.
'';
};
@@ -1022,7 +1022,7 @@ let
promTypes.marathon_sd_config = mkSdConfigModule {
servers = mkOption {
type = types.listOf types.str;
description = ''
description = lib.mdDoc ''
List of URLs to be used to contact Marathon servers. You need to provide at least one server URL.
'';
};
@@ -1048,14 +1048,14 @@ let
options = {
servers = mkOption {
type = types.listOf types.str;
description = ''
description = lib.mdDoc ''
The Zookeeper servers.
'';
};
paths = mkOption {
type = types.listOf types.str;
description = ''
description = lib.mdDoc ''
Paths can point to a single service, or the root of a tree of services.
'';
};
@@ -1097,14 +1097,14 @@ let
{
role = mkOption {
type = types.str;
description = ''
description = lib.mdDoc ''
The OpenStack role of entities that should be discovered.
'';
};
region = mkOption {
type = types.str;
description = ''
description = lib.mdDoc ''
The OpenStack Region.
'';
};
@@ -1165,14 +1165,14 @@ let
promTypes.puppetdb_sd_config = mkSdConfigModule {
url = mkOption {
type = types.str;
description = ''
description = lib.mdDoc ''
The URL of the PuppetDB root query endpoint.
'';
};
query = mkOption {
type = types.str;
description = ''
description = lib.mdDoc ''
Puppet Query Language (PQL) query. Only resources are supported.
https://puppet.com/docs/puppetdb/latest/api/query/v4/pql.html
'';
@@ -1201,7 +1201,7 @@ let
options = {
access_key = mkOption {
type = types.str;
description = ''
description = lib.mdDoc ''
Access key to use. https://console.scaleway.com/project/credentials
'';
};
@@ -1218,7 +1218,7 @@ let
project_id = mkOption {
type = types.str;
description = ''
description = lib.mdDoc ''
Project ID of the targets.
'';
};
@@ -1275,7 +1275,7 @@ let
options = {
account = mkOption {
type = types.str;
description = ''
description = lib.mdDoc ''
The account to use for discovering new targets.
'';
};
@@ -1288,15 +1288,15 @@ let
dns_suffix = mkOption {
type = types.str;
description = ''
description = lib.mdDoc ''
The DNS suffix which should be applied to target.
'';
};
endpoint = mkOption {
type = types.str;
description = ''
The Triton discovery endpoint (e.g. <literal>cmon.us-east-3b.triton.zone</literal>). This is
description = lib.mdDoc ''
The Triton discovery endpoint (e.g. `cmon.us-east-3b.triton.zone`). This is
often the same value as dns_suffix.
'';
};
@@ -1327,21 +1327,21 @@ let
promTypes.uyuni_sd_config = mkSdConfigModule {
server = mkOption {
type = types.str;
description = ''
description = lib.mdDoc ''
The URL to connect to the Uyuni server.
'';
};
username = mkOption {
type = types.str;
description = ''
description = lib.mdDoc ''
Credentials are used to authenticate the requests to Uyuni API.
'';
};
password = mkOption {
type = types.str;
description = ''
description = lib.mdDoc ''
Credentials are used to authenticate the requests to Uyuni API.
'';
};
@@ -1363,14 +1363,14 @@ let
options = {
targets = mkOption {
type = types.listOf types.str;
description = ''
description = lib.mdDoc ''
The targets specified by the target group.
'';
};
labels = mkOption {
type = types.attrsOf types.str;
default = { };
description = ''
description = lib.mdDoc ''
Labels assigned to all metrics scraped from the targets.
'';
};
@@ -1426,7 +1426,7 @@ let
options = {
url = mkOption {
type = types.str;
description = ''
description = lib.mdDoc ''
ServerName extension to indicate the name of the server.
http://tools.ietf.org/html/rfc4366#section-3.1
'';
@@ -1512,7 +1512,7 @@ let
options = {
url = mkOption {
type = types.str;
description = ''
description = lib.mdDoc ''
ServerName extension to indicate the name of the server.
http://tools.ietf.org/html/rfc4366#section-3.1
'';
@@ -1569,7 +1569,7 @@ in
enable = mkOption {
type = types.bool;
default = false;
description = ''
description = lib.mdDoc ''
Enable the Prometheus monitoring daemon.
'';
};
@@ -1578,7 +1578,7 @@ in
type = types.package;
default = pkgs.prometheus;
defaultText = literalExpression "pkgs.prometheus";
description = ''
description = lib.mdDoc ''
The prometheus package that should be used.
'';
};
@@ -1586,7 +1586,7 @@ in
port = mkOption {
type = types.port;
default = 9090;
description = ''
description = lib.mdDoc ''
Port to listen on.
'';
};
@@ -1594,7 +1594,7 @@ in
listenAddress = mkOption {
type = types.str;
default = "0.0.0.0";
description = ''
description = lib.mdDoc ''
Address to listen on for the web interface, API, and telemetry.
'';
};
@@ -1602,8 +1602,8 @@ in
stateDir = mkOption {
type = types.str;
default = "prometheus2";
description = ''
Directory below <literal>/var/lib</literal> to store Prometheus metrics data.
description = lib.mdDoc ''
Directory below `/var/lib` to store Prometheus metrics data.
This directory will be created automatically using systemd's StateDirectory mechanism.
'';
};
@@ -1611,7 +1611,7 @@ in
extraFlags = mkOption {
type = types.listOf types.str;
default = [ ];
description = ''
description = lib.mdDoc ''
Extra commandline options when launching Prometheus.
'';
};
@@ -1619,11 +1619,11 @@ in
enableReload = mkOption {
default = false;
type = types.bool;
description = ''
description = lib.mdDoc ''
Reload prometheus when configuration file changes (instead of restart).
The following property holds: switching to a configuration
(<literal>switch-to-configuration</literal>) that changes the prometheus
(`switch-to-configuration`) that changes the prometheus
configuration only finishes successully when prometheus has finished
loading the new configuration.
'';
@@ -1632,7 +1632,7 @@ in
configText = mkOption {
type = types.nullOr types.lines;
default = null;
description = ''
description = lib.mdDoc ''
If non-null, this option defines the text that is written to
prometheus.yml. If null, the contents of prometheus.yml is generated
from the structured config options.
@@ -1642,7 +1642,7 @@ in
globalConfig = mkOption {
type = promTypes.globalConfig;
default = { };
description = ''
description = lib.mdDoc ''
Parameters that are valid in all configuration contexts. They
also serve as defaults for other configuration sections
'';
@@ -1651,25 +1651,25 @@ in
remoteRead = mkOption {
type = types.listOf promTypes.remote_read;
default = [ ];
description = ''
description = lib.mdDoc ''
Parameters of the endpoints to query from.
See <link xlink:href="https://prometheus.io/docs/prometheus/latest/configuration/configuration/#remote_read">the official documentation</link> for more information.
See [the official documentation](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#remote_read) for more information.
'';
};
remoteWrite = mkOption {
type = types.listOf promTypes.remote_write;
default = [ ];
description = ''
description = lib.mdDoc ''
Parameters of the endpoints to send samples to.
See <link xlink:href="https://prometheus.io/docs/prometheus/latest/configuration/configuration/#remote_write">the official documentation</link> for more information.
See [the official documentation](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#remote_write) for more information.
'';
};
rules = mkOption {
type = types.listOf types.str;
default = [ ];
description = ''
description = lib.mdDoc ''
Alerting and/or Recording rules to evaluate at runtime.
'';
};
@@ -1677,7 +1677,7 @@ in
ruleFiles = mkOption {
type = types.listOf types.path;
default = [ ];
description = ''
description = lib.mdDoc ''
Any additional rules files to include in this configuration.
'';
};
@@ -1685,7 +1685,7 @@ in
scrapeConfigs = mkOption {
type = types.listOf promTypes.scrape_config;
default = [ ];
description = ''
description = lib.mdDoc ''
A list of scrape configurations.
'';
};
@@ -1704,16 +1704,16 @@ in
} ]
'';
default = [ ];
description = ''
description = lib.mdDoc ''
A list of alertmanagers to send alerts to.
See <link xlink:href="https://prometheus.io/docs/prometheus/latest/configuration/configuration/#alertmanager_config">the official documentation</link> for more information.
See [the official documentation](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#alertmanager_config) for more information.
'';
};
alertmanagerNotificationQueueCapacity = mkOption {
type = types.int;
default = 10000;
description = ''
description = lib.mdDoc ''
The capacity of the queue for pending alert manager notifications.
'';
};
@@ -1722,7 +1722,7 @@ in
type = types.nullOr types.str;
default = null;
example = "https://example.com/";
description = ''
description = lib.mdDoc ''
The URL under which Prometheus is externally reachable (for example,
if Prometheus is served via a reverse proxy).
'';
@@ -1750,7 +1750,7 @@ in
type = types.nullOr types.str;
default = null;
example = "15d";
description = ''
description = lib.mdDoc ''
How long to retain samples in storage.
'';
};

46
nixos/modules/services/monitoring/prometheus/pushgateway.nix
View File

@@ -27,7 +27,7 @@ in {
type = types.package;
default = pkgs.prometheus-pushgateway;
defaultText = literalExpression "pkgs.prometheus-pushgateway";
description = ''
description = lib.mdDoc ''
Package that should be used for the prometheus pushgateway.
'';
};
@@ -35,27 +35,27 @@ in {
web.listen-address = mkOption {
type = types.nullOr types.str;
default = null;
description = ''
description = lib.mdDoc ''
Address to listen on for the web interface, API and telemetry.
<literal>null</literal> will default to <literal>:9091</literal>.
`null` will default to `:9091`.
'';
};
web.telemetry-path = mkOption {
type = types.nullOr types.str;
default = null;
description = ''
description = lib.mdDoc ''
Path under which to expose metrics.
<literal>null</literal> will default to <literal>/metrics</literal>.
`null` will default to `/metrics`.
'';
};
web.external-url = mkOption {
type = types.nullOr types.str;
default = null;
description = ''
description = lib.mdDoc ''
The URL under which Pushgateway is externally reachable.
'';
};
@@ -63,11 +63,11 @@ in {
web.route-prefix = mkOption {
type = types.nullOr types.str;
default = null;
description = ''
description = lib.mdDoc ''
Prefix for the internal routes of web endpoints.
Defaults to the path of
<option>services.prometheus.pushgateway.web.external-url</option>.
{option}`services.prometheus.pushgateway.web.external-url`.
'';
};
@@ -75,20 +75,20 @@ in {
type = types.nullOr types.str;
default = null;
example = "10m";
description = ''
description = lib.mdDoc ''
The minimum interval at which to write out the persistence file.
<literal>null</literal> will default to <literal>5m</literal>.
`null` will default to `5m`.
'';
};
log.level = mkOption {
type = types.nullOr (types.enum ["debug" "info" "warn" "error" "fatal"]);
default = null;
description = ''
description = lib.mdDoc ''
Only log messages with the given severity or above.
<literal>null</literal> will default to <literal>info</literal>.
`null` will default to `info`.
'';
};
@@ -96,17 +96,17 @@ in {
type = types.nullOr types.str;
default = null;
example = "logger:syslog?appname=bob&local=7";
description = ''
description = lib.mdDoc ''
Set the log target and format.
<literal>null</literal> will default to <literal>logger:stderr</literal>.
`null` will default to `logger:stderr`.
'';
};
extraFlags = mkOption {
type = types.listOf types.str;
default = [];
description = ''
description = lib.mdDoc ''
Extra commandline options when launching the Pushgateway.
'';
};
@@ -114,26 +114,26 @@ in {
persistMetrics = mkOption {
type = types.bool;
default = false;
description = ''
description = lib.mdDoc ''
Whether to persist metrics to a file.
When enabled metrics will be saved to a file called
<literal>metrics</literal> in the directory
<literal>/var/lib/pushgateway</literal>. The directory below
<literal>/var/lib</literal> can be set using
<option>services.prometheus.pushgateway.stateDir</option>.
`metrics` in the directory
`/var/lib/pushgateway`. The directory below
`/var/lib` can be set using
{option}`services.prometheus.pushgateway.stateDir`.
'';
};
stateDir = mkOption {
type = types.str;
default = "pushgateway";
description = ''
Directory below <literal>/var/lib</literal> to store metrics.
description = lib.mdDoc ''
Directory below `/var/lib` to store metrics.
This directory will be created automatically using systemd's
StateDirectory mechanism when
<option>services.prometheus.pushgateway.persistMetrics</option>
{option}`services.prometheus.pushgateway.persistMetrics`
is enabled.
'';
};

4
nixos/modules/services/monitoring/prometheus/xmpp-alerts.nix
View File

@@ -21,9 +21,9 @@ in
type = settingsFormat.type;
default = {};
description = ''
description = lib.mdDoc ''
Configuration for prometheus xmpp-alerts, see
<link xlink:href="https://github.com/jelmer/prometheus-xmpp-alerts/blob/master/xmpp-alerts.yml.example"/>
<https://github.com/jelmer/prometheus-xmpp-alerts/blob/master/xmpp-alerts.yml.example>
for supported values.
'';
};