Doc attributes (#479)

Co-authored-by: Andrew Klychkov <[email protected]> Co-authored-by: Douglas J Hunley <[email protected]>
ansible-collections · May 22, 2023 · 248ca0e · 248ca0e
1 parent ecae1de
commit 248ca0e
Show file tree

Hide file tree

Showing 24 changed files with 140 additions and 109 deletions.
diff --git a/plugins/doc_fragments/postgres.py b/plugins/doc_fragments/postgres.py
@@ -71,6 +71,11 @@ class ModuleDocFragment(object):
     type: dict
     default: {}
     version_added: '2.3.0'
+
+attributes:
+  check_mode:
+    description: Can run in check_mode and return changed status prediction without modifying target.
+
 notes:
 - The default authentication assumes that you are either logging in as or sudo'ing to the C(postgres) account on the host.
 - To avoid "Peer authentication failed for user postgres" error,
@@ -82,5 +87,6 @@ class ModuleDocFragment(object):
 - For Ubuntu-based systems, install the C(postgresql), C(libpq-dev), and C(python-psycopg2) packages
   on the remote host before using this module.
 - The ca_cert parameter requires at least Postgres version 8.4 and I(psycopg2) version 2.4.3.
+
 requirements: [ psycopg2 ]
 '''
diff --git a/plugins/modules/postgresql_copy.py b/plugins/modules/postgresql_copy.py
@@ -79,11 +79,16 @@
 notes:
 - Supports PostgreSQL version 9.4+.
 - COPY command is only allowed to database superusers.
-- If I(check_mode=true), we just check the src/dst table availability
-  and return the COPY query that actually has not been executed.
-- If i(check_mode=true) and the source has been passed as SQL, the module
-  will execute it and rolled the transaction back but pay attention
-  it can affect database performance (e.g., if SQL collects a lot of data).
+
+attributes:
+  check_mode:
+    support: partial
+    details:
+      - If I(check_mode=true), we just check the src/dst table availability
+        and return the COPY query that actually has not been executed.
+      - If i(check_mode=true) and the source has been passed as SQL, the module
+        will execute it and roll the transaction back, but pay attention
+        it can affect database performance (e.g., if SQL collects a lot of data).
 
 seealso:
 - name: COPY command reference

diff --git a/plugins/modules/postgresql_db.py b/plugins/modules/postgresql_db.py
@@ -20,13 +20,6 @@
     type: str
     required: true
     aliases: [ db ]
-  port:
-    description:
-      - Database port to connect (if needed).
-    type: int
-    default: 5432
-    aliases:
-      - login_port
   owner:
     description:
       - Name of the role to set as owner of the database.
@@ -153,13 +146,18 @@
 - module: community.postgresql.postgresql_tablespace
 - module: community.postgresql.postgresql_info
 - module: community.postgresql.postgresql_ping
+
 notes:
 - State C(dump) and C(restore) don't require I(psycopg2) since version 2.8.
-- Supports C(check_mode).
+
+attributes:
+  check_mode:
+    support: full
+
 author: "Ansible Core Team"
+
 extends_documentation_fragment:
 - community.postgresql.postgres
-
 '''
 
 EXAMPLES = r'''

diff --git a/plugins/modules/postgresql_ext.py b/plugins/modules/postgresql_ext.py
@@ -100,19 +100,23 @@
 - name: DROP EXTENSION reference
   description: Complete reference of the DROP EXTENSION command documentation.
   link: https://www.postgresql.org/docs/current/sql-droppublication.html
+
 notes:
-- Supports C(check_mode).
 - Incomparable versions, for example PostGIS ``unpackaged``, cannot be installed.
-requirements: [ psycopg2 ]
+
+attributes:
+  check_mode:
+    support: full
+
 author:
 - Daniel Schep (@dschep)
 - Thomas O'Donnell (@andytom)
 - Sandro Santilli (@strk)
 - Andrew Klychkov (@Andersson007)
 - Keith Fiske (@keithf4)
+
 extends_documentation_fragment:
 - community.postgresql.postgres
-
 '''
 
 EXAMPLES = r'''

diff --git a/plugins/modules/postgresql_idx.py b/plugins/modules/postgresql_idx.py
@@ -135,17 +135,19 @@
   link: https://www.postgresql.org/docs/current/sql-dropindex.html
 
 notes:
-- Supports C(check_mode).
 - The index building process can affect database performance.
 - To avoid table locks on production databases, use I(concurrent=true) (default behavior).
 
+attributes:
+  check_mode:
+    support: full
+
 author:
 - Andrew Klychkov (@Andersson007)
 - Thomas O'Donnell (@andytom)
 
 extends_documentation_fragment:
 - community.postgresql.postgres
-
 '''
 
 EXAMPLES = r'''

diff --git a/plugins/modules/postgresql_info.py b/plugins/modules/postgresql_info.py
@@ -47,15 +47,19 @@
     type: bool
     default: true
     version_added: '0.2.0'
+
+attributes:
+  check_mode:
+    support: full
+
 seealso:
 - module: community.postgresql.postgresql_ping
+
 author:
 - Andrew Klychkov (@Andersson007)
+
 extends_documentation_fragment:
 - community.postgresql.postgres
-
-notes:
-- Supports C(check_mode).
 '''
 
 EXAMPLES = r'''

diff --git a/plugins/modules/postgresql_lang.py b/plugins/modules/postgresql_lang.py
@@ -78,24 +78,6 @@
     type: str
     default: present
     choices: [ absent, present ]
-  login_unix_socket:
-    description:
-      - Path to a Unix domain socket for local connections.
-    type: str
-  ssl_mode:
-    description:
-      - Determines whether or with what priority a secure SSL TCP/IP connection will be negotiated with the server.
-      - See U(https://www.postgresql.org/docs/current/static/libpq-ssl.html) for more information on the modes.
-      - Default of C(prefer) matches libpq default.
-    type: str
-    default: prefer
-    choices: [ allow, disable, prefer, require, verify-ca, verify-full ]
-  ca_cert:
-    description:
-      - Specifies the name of a file containing SSL certificate authority (CA) certificate(s).
-      - If the file exists, the server's certificate will be verified to be signed by one of these authorities.
-    type: str
-    aliases: [ ssl_rootcert ]
   owner:
     description:
       - Set an owner for the language.
@@ -123,14 +105,17 @@
 - name: DROP LANGUAGE reference
   description: Complete reference of the DROP LANGUAGE command documentation.
   link: https://www.postgresql.org/docs/current/sql-droplanguage.html
+
+attributes:
+  check_mode:
+    support: full
+
 author:
 - Jens Depuydt (@jensdepuydt)
 - Thomas O'Donnell (@andytom)
+
 extends_documentation_fragment:
 - community.postgresql.postgres
-
-notes:
-- Supports C(check_mode).
 '''
 
 EXAMPLES = r'''

diff --git a/plugins/modules/postgresql_membership.py b/plugins/modules/postgresql_membership.py
@@ -87,12 +87,16 @@
 - name: PostgreSQL role attributes reference
   description: Complete reference of the PostgreSQL role attributes documentation.
   link: https://www.postgresql.org/docs/current/role-attributes.html
+
+attributes:
+  check_mode:
+    support: full
+
 author:
 - Andrew Klychkov (@Andersson007)
+
 extends_documentation_fragment:
 - community.postgresql.postgres
-notes:
-- Supports C(check_mode).
 '''
 
 EXAMPLES = r'''

diff --git a/plugins/modules/postgresql_owner.py b/plugins/modules/postgresql_owner.py
@@ -81,12 +81,16 @@
 - name: PostgreSQL REASSIGN OWNED command reference
   description: Complete reference of the PostgreSQL REASSIGN OWNED command documentation.
   link: https://www.postgresql.org/docs/current/sql-reassign-owned.html
+
+attributes:
+  check_mode:
+    support: full
+
 author:
 - Andrew Klychkov (@Andersson007)
+
 extends_documentation_fragment:
 - community.postgresql.postgres
-notes:
-- Supports C(check_mode).
 '''
 
 EXAMPLES = r'''

diff --git a/plugins/modules/postgresql_pg_hba.py b/plugins/modules/postgresql_pg_hba.py
@@ -144,15 +144,22 @@
      After the C(pg_hba) file is rewritten by the M(community.postgresql.postgresql_pg_hba) module, the ip specific rule will be sorted above the range rule.
      And then it will hit, which will give unexpected results.
    - With the 'order' parameter you can control which field is used to sort first, next and last.
-   - The module supports a check mode and a diff mode.
 
 seealso:
 - name: PostgreSQL pg_hba.conf file reference
   description: Complete reference of the PostgreSQL pg_hba.conf file documentation.
   link: https://www.postgresql.org/docs/current/auth-pg-hba-conf.html
 
 requirements:
-    - ipaddress
+  - ipaddress
+
+attributes:
+  check_mode:
+    support: full
+    description: Can run in check_mode and return changed status prediction without modifying target
+  diff_mode:
+    support: full
+    description: Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode
 
 author:
 - Sebastiaan Mannem (@sebasmannem)

diff --git a/plugins/modules/postgresql_ping.py b/plugins/modules/postgresql_ping.py
@@ -37,12 +37,13 @@
     version_added: '0.2.0'
 seealso:
 - module: community.postgresql.postgresql_info
+attributes:
+  check_mode:
+    support: full
 author:
 - Andrew Klychkov (@Andersson007)
 extends_documentation_fragment:
 - community.postgresql.postgres
-notes:
-- Supports C(check_mode).
 '''
 
 EXAMPLES = r'''

diff --git a/plugins/modules/postgresql_privs.py b/plugins/modules/postgresql_privs.py
@@ -120,21 +120,6 @@
     - Mutually exclusive with I(login_password).
     type: str
     default: ''
-  ssl_mode:
-    description:
-    - Determines whether or with what priority a secure SSL TCP/IP connection will be negotiated with the server.
-    - See U(https://www.postgresql.org/docs/current/static/libpq-ssl.html) for more information on the modes.
-    - Default of C(prefer) matches libpq default.
-    type: str
-    default: prefer
-    choices: [ allow, disable, prefer, require, verify-ca, verify-full ]
-  ca_cert:
-    description:
-    - Specifies the name of a file containing SSL certificate authority (CA) certificate(s).
-    - If the file exists, the server's certificate will be verified to be signed by one of these authorities.
-    type: str
-    aliases:
-    - ssl_rootcert
   trust_input:
     description:
     - If C(false), check whether values of parameters I(roles), I(target_roles), I(session_role),
@@ -157,7 +142,6 @@
     version_added: '1.2.0'
 
 notes:
-- Supports C(check_mode).
 - Parameters that accept comma separated lists (I(privs), I(objs), I(roles))
   have singular alias names (I(priv), I(obj), I(role)).
 - To revoke only C(GRANT OPTION) for a specific object, set I(state) to
@@ -184,10 +168,13 @@
   description: Complete reference of the PostgreSQL REVOKE command documentation.
   link: https://www.postgresql.org/docs/current/sql-revoke.html
 
+attributes:
+  check_mode:
+    support: full
+
 extends_documentation_fragment:
 - community.postgresql.postgres
 
-
 author:
 - Bernhard Weitzhofer (@b6d)
 - Tobias Birkefeld (@tcraxs)

diff --git a/plugins/modules/postgresql_publication.py b/plugins/modules/postgresql_publication.py
@@ -74,9 +74,14 @@
     type: bool
     default: true
     version_added: '0.2.0'
+
 notes:
 - PostgreSQL version must be 10 or greater.
-- Supports C(check_mode).
+
+attributes:
+  check_mode:
+    support: full
+
 seealso:
 - name: CREATE PUBLICATION reference
   description: Complete reference of the CREATE PUBLICATION command documentation.

diff --git a/plugins/modules/postgresql_query.py b/plugins/modules/postgresql_query.py
@@ -116,14 +116,18 @@
 - name: PostgreSQL Schema reference
   description: Complete reference of the PostgreSQL schema documentation.
   link: https://www.postgresql.org/docs/current/ddl-schemas.html
+
+attributes:
+  check_mode:
+    support: full
+
 author:
 - Felix Archambault (@archf)
 - Andrew Klychkov (@Andersson007)
 - Will Rouesnel (@wrouesnel)
+
 extends_documentation_fragment:
 - community.postgresql.postgres
-notes:
-- Supports C(check_mode).
 '''
 
 EXAMPLES = r'''

diff --git a/plugins/modules/postgresql_schema.py b/plugins/modules/postgresql_schema.py
@@ -52,20 +52,6 @@
     - Drop schema with CASCADE to remove child objects.
     type: bool
     default: false
-  ssl_mode:
-    description:
-      - Determines whether or with what priority a secure SSL TCP/IP connection will be negotiated with the server.
-      - See U(https://www.postgresql.org/docs/current/static/libpq-ssl.html) for more information on the modes.
-      - Default of C(prefer) matches libpq default.
-    type: str
-    default: prefer
-    choices: [ allow, disable, prefer, require, verify-ca, verify-full ]
-  ca_cert:
-    description:
-      - Specifies the name of a file containing SSL certificate authority (CA) certificate(s).
-      - If the file exists, the server's certificate will be verified to be signed by one of these authorities.
-    type: str
-    aliases: [ ssl_rootcert ]
   trust_input:
     description:
     - If C(false), check whether values of parameters I(schema), I(owner), I(session_role) are potentially dangerous.
@@ -86,13 +72,17 @@
 - name: DROP SCHEMA reference
   description: Complete reference of the DROP SCHEMA command documentation.
   link: https://www.postgresql.org/docs/current/sql-dropschema.html
+
+attributes:
+  check_mode:
+    support: full
+
 author:
 - Flavien Chantelot (@Dorn-) <[email protected]>
 - Thomas O'Donnell (@andytom)
+
 extends_documentation_fragment:
 - community.postgresql.postgres
-notes:
-- Supports C(check_mode).
 '''
 
 EXAMPLES = r'''