improve module documentation (#47)

* improve module documentation * add changelog * Delete requirements.py * improve format macros usage * format url
lowlydba · Apr 3, 2022 · 507f099 · 507f099
1 parent 613dbde
commit 507f099
Show file tree

Hide file tree

Showing 16 changed files with 57 additions and 15 deletions.
diff --git a/changelogs/fragments/47-improve-module-documentation.yml b/changelogs/fragments/47-improve-module-documentation.yml
@@ -0,0 +1,3 @@
+minor_changes:
+- Add DbaTools module requirement to documentation and fix missing examples.
+  (https://github.com/lowlydba/lowlydba.sqlserver/pull/47)
diff --git a/plugins/modules/agent_job.py b/plugins/modules/agent_job.py
@@ -52,14 +52,16 @@
     required: false
   force:
     description:
-      - If this switch is enabled, any job categories will be created if they don't exist already.
+      - If I(force=true), any job categories will be created if they don't exist already.
     type: bool
     default: false
 author: "John McCall (@lowlydba)"
 notes:
   - Check mode is supported.
   - On slower hardware, stale job component data may be returned (i.e., a previous or default job category).
     Configuring each component (schedule, step, category, etc.) individually is recommended for this reason.
+requirements:
+  - L(dbatools,https://www.powershellgallery.com/packages/dbatools/) PowerShell module
 extends_documentation_fragment:
   - lowlydba.sqlserver.sql_credentials
   - lowlydba.sqlserver.state
@@ -68,6 +70,9 @@
 EXAMPLES = r'''
 - name: Create a job schedule
   lowlydba.sqlserver.agent_job:
+    sql_instance: sql-01.myco.io
+    job: MyJob
+    force: true
 '''
 
 RETURN = r'''

diff --git a/plugins/modules/agent_job_category.py b/plugins/modules/agent_job_category.py
@@ -20,13 +20,14 @@
   category_type:
     description:
       - The type of category. This can be C(LocalJob), C(MultiServerJob) or C(None).
-        If no category is used all categories types will be removed.
     required: false
     type: str
     choices: ['LocalJob', 'MultiServerJob', 'None']
 author: "John McCall (@lowlydba)"
 notes:
   - Check mode is supported.
+requirements:
+  - L(dbatools,https://www.powershellgallery.com/packages/dbatools/) PowerShell module
 extends_documentation_fragment:
   - lowlydba.sqlserver.sql_credentials
   - lowlydba.sqlserver.state

diff --git a/plugins/modules/agent_job_schedule.py b/plugins/modules/agent_job_schedule.py
@@ -21,7 +21,7 @@
     description:
       - The name of the job that has the schedule.
       - Schedules and jobs can also be associated via agent_job.
-      - See https://docs.dbatools.io/New-DbaAgentSchedule for more detailed usage.
+      - See U(https://docs.dbatools.io/New-DbaAgentSchedule) for more detailed usage.
     type: str
     required: true
   enabled:
@@ -33,7 +33,7 @@
     description:
       - The force parameter will ignore some errors in the parameters and assume defaults.
         It will also remove the any present schedules with the same name for the specific job.
-        If force is used the default will be 'Once'.
+        If I(force=true) the default will be 'Once'.
     type: bool
   frequency_type:
     description:
@@ -47,8 +47,8 @@
         Allowed values for frequency_type 'Daily' - EveryDay or a number between 1 and 365.
         Allowed values for frequency_type 'Weekly' - Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Weekdays, Weekend or EveryDay.
         Allowed values for frequency_type 'Monthly' - Numbers 1 to 31 for each day of the month.
-        If "Weekdays", "Weekend" or "EveryDay" is used it over writes any other value that has been passed before.
-        If force is used the default will be 1.
+        If 'Weekdays', 'Weekend' or 'EveryDay' is used it over writes any other value that has been passed before.
+        If I(force=true) the default will be 1.
     type: str
     required: false
   frequency_subday_type:
@@ -64,14 +64,14 @@
     required: false
   frequency_relative_interval:
     description:
-      - A job's occurrence of frequency_interval in each month, if frequency_interval is 32 ('MonthlyRelative').
+      - A job's occurrence of frequency_interval in each month, if I(frequency_interval=32) ('MonthlyRelative').
     type: str
     required: false
     choices: ['Unused', 'First', 'Second', 'Third', 'Fourth', 'Last']
   frequency_recurrence_factor:
     description:
       - The number of weeks or months between the scheduled execution of a job.
-        Used only if frequency_type is 'Weekly', 'Monthly' or 'MonthlyRelative'.
+        Required if I(frequency_type='Weekly'), I(frequency_type='Monthly') or I(frequency_type='MonthlyRelative').
     type: int
     required: false
   start_date:
@@ -83,24 +83,26 @@
   end_date:
     description:
       - The date on which execution of a job can stop.
-        If force is used the end date will be '9999-12-31'
+        If I(force=true) the end date will be '9999-12-31'
     type: str
     required: false
   start_time:
     description:
       - The time on any day to begin execution of a job. Format HHMMSS / 24 hour clock.
-      - If force is used the start time will be '00:00:00'
+      - If I(force=true) the start time will be '00:00:00'
     type: str
     required: false
   end_time:
     description:
       - The time on any day to end execution of a job. Format HHMMSS / 24 hour clock.
-        If force is used the start time will be '23:59:59'
+        If (force=true) the start time will be '23:59:59'
     type: str
     required: false
 author: "John McCall (@lowlydba)"
 notes:
   - Check mode is supported.
+requirements:
+  - L(dbatools,https://www.powershellgallery.com/packages/dbatools/) PowerShell module
 extends_documentation_fragment:
   - lowlydba.sqlserver.sql_credentials
   - lowlydba.sqlserver.state

diff --git a/plugins/modules/agent_job_step.py b/plugins/modules/agent_job_step.py
@@ -20,7 +20,7 @@
   step_id:
     description:
       - The sequence identification number for the job step. Step identification numbers start at 1 and increment without gaps.
-        Required if state is C(present).
+        Required if I(state=present).
     required: false
     type: int
   step_name:
@@ -87,6 +87,8 @@
 author: "John McCall (@lowlydba)"
 notes:
   - Check mode is supported.
+requirements:
+  - L(dbatools,https://www.powershellgallery.com/packages/dbatools/) PowerShell module
 extends_documentation_fragment:
   - lowlydba.sqlserver.sql_credentials
   - lowlydba.sqlserver.state
@@ -95,6 +97,11 @@
 EXAMPLES = r'''
 - name: Create a job step
   lowlydba.sqlserver.agent_job_step:
+    sql_instance: sql-01.myco.io
+    job: MyJob
+    step_name: Step1
+    step_id: 1
+    command: "TRUNCATE TABLE dbo.TestData"
 '''
 
 RETURN = r'''

diff --git a/plugins/modules/database.py b/plugins/modules/database.py
@@ -64,6 +64,8 @@
 author: "John McCall (@lowlydba)"
 notes:
   - Check mode is supported.
+requirements:
+  - L(dbatools,https://www.powershellgallery.com/packages/dbatools/) PowerShell module
 extends_documentation_fragment:
   - lowlydba.sqlserver.sql_credentials
   - lowlydba.sqlserver.state

diff --git a/plugins/modules/login.py b/plugins/modules/login.py
@@ -42,7 +42,7 @@
   password_must_change:
     description:
       - Enforces user must change password at next login.
-        When specified will enforce PasswordExpirationEnabled and PasswordPolicyEnforced as they are required for the must change.
+        When specified will enforce C(password_expiration_enabled) and C(password_policy_enforced) as they are required.
     type: bool
     required: false
   password_policy_enforced:
@@ -52,10 +52,12 @@
     required: false
   password_expiration_enabled:
     description:
-      - Enforces password expiration policy. Requires PasswordPolicyEnforced to be enabled.
+      - Enforces password expiration policy. Requires I(password_policy_enforced=true).
     type: bool
     required: false
 author: "John McCall (@lowlydba)"
+requirements:
+  - L(dbatools,https://www.powershellgallery.com/packages/dbatools/) PowerShell module
 extends_documentation_fragment:
   - lowlydba.sqlserver.sql_credentials
   - lowlydba.sqlserver.state
@@ -65,6 +67,8 @@
 - name:
   lowlydba.sqlserver.login:
     sql_instance: sql-01.myco.io
+    login: TheIntern
+    password: ReallyComplexStuff12345!
 '''
 
 RETURN = r'''

diff --git a/plugins/modules/maintenance_solution.py b/plugins/modules/maintenance_solution.py
@@ -7,7 +7,7 @@
 DOCUMENTATION = r'''
 ---
 module: maintenance_solution
-short_description: Install/update Maintenance Solution
+short_description: Install/update Maintenance Solution by Ola Hallengren.
 description:
   - A wrapper for Install-DbaMaintenanceSolution to fetch the latest version of the Ola Hallengren's Maintenance Solution,
     or install from a local cached version.
@@ -79,6 +79,8 @@
 author: "John McCall (@lowlydba)"
 notes:
     - Check mode is not supported.
+requirements:
+  - L(dbatools,https://www.powershellgallery.com/packages/dbatools/) PowerShell module
 extends_documentation_fragment:
   - lowlydba.sqlserver.sql_credentials
 '''

diff --git a/plugins/modules/memory.py b/plugins/modules/memory.py
@@ -21,6 +21,8 @@
 author: "John McCall (@lowlydba)"
 notes:
   - Check mode is supported.
+requirements:
+  - L(dbatools,https://www.powershellgallery.com/packages/dbatools/) PowerShell module
 extends_documentation_fragment:
   - lowlydba.sqlserver.sql_credentials
 '''

diff --git a/plugins/modules/nonquery.py b/plugins/modules/nonquery.py
@@ -31,6 +31,8 @@
 author: "John McCall (@lowlydba)"
 notes:
   - Check mode is supported, but the nonquery will not be parsed.
+requirements:
+  - L(dbatools,https://www.powershellgallery.com/packages/dbatools/) PowerShell module
 extends_documentation_fragment:
   - lowlydba.sqlserver.sql_credentials
 '''

diff --git a/plugins/modules/resource_governor.py b/plugins/modules/resource_governor.py
@@ -27,6 +27,8 @@
 author: "John McCall (@lowlydba)"
 notes:
   - Check mode is supported.
+requirements:
+  - L(dbatools,https://www.powershellgallery.com/packages/dbatools/) PowerShell module
 extends_documentation_fragment:
   - lowlydba.sqlserver.sql_credentials
 '''

diff --git a/plugins/modules/rg_resource_pool.py b/plugins/modules/rg_resource_pool.py
@@ -60,6 +60,8 @@
     type: int
     required: false
 author: "John McCall (@lowlydba)"
+requirements:
+  - L(dbatools,https://www.powershellgallery.com/packages/dbatools/) PowerShell module
 extends_documentation_fragment:
   - lowlydba.sqlserver.sql_credentials
   - lowlydba.sqlserver.state

diff --git a/plugins/modules/rg_workload_group.py b/plugins/modules/rg_workload_group.py
@@ -61,6 +61,8 @@
     type: int
     required: false
 author: "John McCall (@lowlydba)"
+requirements:
+  - L(dbatools,https://www.powershellgallery.com/packages/dbatools/) PowerShell module
 extends_documentation_fragment:
   - lowlydba.sqlserver.sql_credentials
   - lowlydba.sqlserver.state

diff --git a/plugins/modules/sp_configure.py b/plugins/modules/sp_configure.py
@@ -27,6 +27,8 @@
 author: "Sudhir Koduri (@kodurisudhir)"
 notes:
   - Check mode is supported.
+requirements:
+  - L(dbatools,https://www.powershellgallery.com/packages/dbatools/) PowerShell module
 extends_documentation_fragment:
   - lowlydba.sqlserver.sql_credentials
 '''

diff --git a/plugins/modules/sp_whoisactive.py b/plugins/modules/sp_whoisactive.py
@@ -32,6 +32,8 @@
 author: "John McCall (@lowlydba)"
 notes:
   - Check mode is supported.
+requirements:
+  - L(dbatools,https://www.powershellgallery.com/packages/dbatools/) PowerShell module
 extends_documentation_fragment:
   - lowlydba.sqlserver.sql_credentials
 '''

diff --git a/plugins/modules/traceflag.py b/plugins/modules/traceflag.py
@@ -27,6 +27,8 @@
 author: "Sudhir Koduri (@kodurisudhir)"
 notes:
   - Check mode is supported.
+requirements:
+  - L(dbatools,https://www.powershellgallery.com/packages/dbatools/) PowerShell module
 extends_documentation_fragment:
   - lowlydba.sqlserver.sql_credentials
 '''