From b97c235e37c91511c2e7533ab6794480e4cc445a Mon Sep 17 00:00:00 2001 From: Emily Date: Thu, 22 Jun 2023 02:34:49 +0100 Subject: treewide: tweak DocBook docs for conversion These help `nix-munge-doc` automate more of the Markdown conversion process. See the following nixpkgs commits for explanations of many of these changes: * https://github.com/NixOS/nixpkgs/commit/275a34e0d8a937a81b267e47302dd8a92fa781df * https://github.com/NixOS/nixpkgs/commit/694d5b19d30bf66687b42fb77f43ea7cd1002a62 * https://github.com/NixOS/nixpkgs/commit/f1d39b6d6187997b630647400c5efe5b01e06a23 * https://github.com/NixOS/nixpkgs/commit/16102dce2fbad670bd47dd75c860a8daa5fe47ad I couldn't think of any particularly good way to format the `system.defaults` breadcrumbs, so I just made them standalone paragraphs. They weren't rendering correctly in DocBook anyway. --- modules/services/postgresql/default.nix | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'modules/services/postgresql') diff --git a/modules/services/postgresql/default.nix b/modules/services/postgresql/default.nix index bcaf95e..e6feb96 100644 --- a/modules/services/postgresql/default.nix +++ b/modules/services/postgresql/default.nix @@ -88,7 +88,7 @@ in via the Unix socket, and md5 password authentication will be used for users connecting via TCP. Any added rules will be inserted above the default rules. If you'd like to replace the - default rules entirely, you can use lib.mkForce in your + default rules entirely, you can use lib.mkForce in your module. ''; }; @@ -159,7 +159,7 @@ in For more information on how to specify the target and on which privileges exist, see the GRANT syntax. - The attributes are used as GRANT ''${attrValue} ON ''${attrName}. + The attributes are used as GRANT ''${attrValue} ON ''${attrName}. ''; example = literalExpression '' { @@ -237,8 +237,8 @@ in for an overview of postgresql.conf. - String values will automatically be enclosed in single quotes. Single quotes will be - escaped with two single quotes as described by the upstream documentation linked above. + String values will automatically be enclosed in single quotes. Single quotes will be + escaped with two single quotes as described by the upstream documentation linked above. ''; example = literalExpression '' -- cgit v1.2.3 From e65131e69cab1b18fb49b572b983a18720502e1b Mon Sep 17 00:00:00 2001 From: Emily Date: Thu, 22 Jun 2023 12:21:32 +0100 Subject: treewide: convert all option docs to Markdown This process was automated by [my fork of `nix-doc-munge`]; thanks to @pennae for writing this tool! It automatically checks that the resulting documentation doesn't change, although my fork loosens this a little to ignore some irrelevant whitespace and typographical differences. As of this commit there is no DocBook remaining in the options documentation. You can play along at home if you want to reproduce this commit: $ NIX_PATH=nixpkgs=flake:nixpkgs/c1bca7fe84c646cfd4ebf3482c0e6317a0b13f22 \ nix shell nixpkgs#coreutils \ -c find . -name '*.nix' \ -exec nix run github:emilazy/nix-doc-munge/0a7190f600027bf7baf6cb7139e4d69ac2f51062 \ {} + [my fork of `nix-doc-munge`]: https://github.com/emilazy/nix-doc-munge --- modules/services/postgresql/default.nix | 66 +++++++++++++++++---------------- 1 file changed, 34 insertions(+), 32 deletions(-) (limited to 'modules/services/postgresql') diff --git a/modules/services/postgresql/default.nix b/modules/services/postgresql/default.nix index e6feb96..018b46e 100644 --- a/modules/services/postgresql/default.nix +++ b/modules/services/postgresql/default.nix @@ -40,12 +40,12 @@ in services.postgresql = { - enable = mkEnableOption "PostgreSQL Server"; + enable = mkEnableOption (lib.mdDoc "PostgreSQL Server"); package = mkOption { type = types.package; example = literalExpression "pkgs.postgresql_11"; - description = '' + description = lib.mdDoc '' PostgreSQL package to use. ''; }; @@ -53,7 +53,7 @@ in port = mkOption { type = types.int; default = 5432; - description = '' + description = lib.mdDoc '' The port on which PostgreSQL listens. ''; }; @@ -61,14 +61,14 @@ in checkConfig = mkOption { type = types.bool; default = true; - description = "Check the syntax of the configuration file at compile time"; + description = lib.mdDoc "Check the syntax of the configuration file at compile time"; }; dataDir = mkOption { type = types.path; defaultText = literalExpression ''"/var/lib/postgresql/''${config.services.postgresql.package.psqlSchema}"''; example = "/var/lib/postgresql/11"; - description = '' + description = lib.mdDoc '' The data directory for PostgreSQL. If left as the default value this directory will automatically be created before the PostgreSQL server starts, otherwise the sysadmin is responsible for ensuring the directory exists with appropriate ownership @@ -79,16 +79,16 @@ in authentication = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Defines how users authenticate themselves to the server. See the - - PostgreSQL documentation for pg_hba.conf + [ + PostgreSQL documentation for pg_hba.conf](https://www.postgresql.org/docs/current/auth-pg-hba-conf.html) for details on the expected format of this option. By default, peer based authentication will be used for users connecting via the Unix socket, and md5 password authentication will be used for users connecting via TCP. Any added rules will be inserted above the default rules. If you'd like to replace the - default rules entirely, you can use lib.mkForce in your + default rules entirely, you can use `lib.mkForce` in your module. ''; }; @@ -96,7 +96,7 @@ in identMap = mkOption { type = types.lines; default = ""; - description = '' + description = lib.mdDoc '' Defines the mapping from system users to database users. The general form is: @@ -109,8 +109,8 @@ in type = with types; listOf str; default = []; example = [ "--data-checksums" "--allow-group-access" ]; - description = '' - Additional arguments passed to initdb during data dir + description = lib.mdDoc '' + Additional arguments passed to `initdb` during data dir initialisation. ''; }; @@ -118,7 +118,7 @@ in initialScript = mkOption { type = types.nullOr types.path; default = null; - description = '' + description = lib.mdDoc '' A file containing SQL statements to execute on first startup. ''; }; @@ -126,7 +126,7 @@ in ensureDatabases = mkOption { type = types.listOf types.str; default = []; - description = '' + description = lib.mdDoc '' Ensures that the specified databases exist. This option will never delete existing databases, especially not when the value of this option is changed. This means that databases created once through this option or @@ -143,14 +143,14 @@ in options = { name = mkOption { type = types.str; - description = '' + description = lib.mdDoc '' Name of the user to ensure. ''; }; ensurePermissions = mkOption { type = types.attrsOf types.str; default = {}; - description = '' + description = lib.mdDoc '' Permissions to ensure for the user, specified as an attribute set. The attribute names specify the database and tables to grant the permissions for. The attribute values specify the permissions to grant. You may specify one or @@ -158,8 +158,8 @@ in For more information on how to specify the target and on which privileges exist, see the - GRANT syntax. - The attributes are used as GRANT ''${attrValue} ON ''${attrName}. + [GRANT syntax](https://www.postgresql.org/docs/current/sql-grant.html). + The attributes are used as `GRANT ''${attrValue} ON ''${attrName}`. ''; example = literalExpression '' { @@ -171,7 +171,7 @@ in }; }); default = []; - description = '' + description = lib.mdDoc '' Ensures that the specified users exist and have at least the ensured permissions. The PostgreSQL users will be identified using peer authentication. This authenticates the Unix user with the same name only, and that without the need for a password. @@ -200,7 +200,7 @@ in enableTCPIP = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether PostgreSQL should listen on all network interfaces. If disabled, the database can only be accessed via its Unix domain socket or via TCP connections to localhost. @@ -211,9 +211,9 @@ in type = types.str; default = "[%p] "; example = "%m [%p] "; - description = '' + description = lib.mdDoc '' A printf-style string that is output at the beginning of each log line. - Upstream default is '%m [%p] ', i.e. it includes the timestamp. We do + Upstream default is `'%m [%p] '`, i.e. it includes the timestamp. We do not include the timestamp, because journal has it anyway. ''; }; @@ -222,24 +222,26 @@ in type = types.listOf types.path; default = []; example = literalExpression "with pkgs.postgresql_11.pkgs; [ postgis pg_repack ]"; - description = '' + description = lib.mdDoc '' List of PostgreSQL plugins. PostgreSQL version for each plugin should - match version for services.postgresql.package value. + match version for `services.postgresql.package` value. ''; }; settings = mkOption { type = with types; attrsOf (oneOf [ bool float int str ]); default = {}; - description = '' + description = lib.mdDoc '' PostgreSQL configuration. Refer to - - for an overview of postgresql.conf. + + for an overview of `postgresql.conf`. - + ::: {.note} + String values will automatically be enclosed in single quotes. Single quotes will be escaped with two single quotes as described by the upstream documentation linked above. - + + ::: ''; example = literalExpression '' { @@ -255,8 +257,8 @@ in recoveryConfig = mkOption { type = types.nullOr types.lines; default = null; - description = '' - Contents of the recovery.conf file. + description = lib.mdDoc '' + Contents of the {file}`recovery.conf` file. ''; }; @@ -265,7 +267,7 @@ in default = "postgres"; internal = true; readOnly = true; - description = '' + description = lib.mdDoc '' PostgreSQL superuser account to use for various operations. Internal since changing this value would lead to breakage while setting up databases. ''; -- cgit v1.2.3