Skip to content

Commit

Permalink
Improved module documentation
Browse files Browse the repository at this point in the history 
Details:

* Removed IBM email addresses of Andreas Scheuring and Juergen Leopold.

* Removed Ansible and its minimum version 2.2 from the prerequisites.

* Added explicit type definitions to module input parameters, because the
  implied types are not shown in the generated docs.

* Changed description of defaults to null where they had text such
  as 'the real HMC' or 'no properties changed' and made sure the
  description of the parameter is clear about what that means.

* Simplified title of the modules and made sure they are understandable
  by non Z persons.

Signed-off-by: Andreas Maier <maiera@de.ibm.com>
  • Loading branch information
@andy-maier
andy-maier committed May 5, 2020
1 parent 533c397 commit f118011
Show file tree
Hide file tree
Showing 22 changed files with 349 additions and 401 deletions.
27 changes: 13 additions & 14 deletions docs/gen/zhmc_adapter_module.rst
View file
Expand Up @@ -5,8 +5,8 @@
.. _zhmc_adapter_module:


zhmc_adapter -- Manages an adapter in a CPC
+++++++++++++++++++++++++++++++++++++++++++
zhmc_adapter -- Manages adapters of Z systems
+++++++++++++++++++++++++++++++++++++++++++++


.. contents::
Expand All @@ -16,18 +16,17 @@ zhmc_adapter -- Manages an adapter in a CPC

Synopsis
--------
- Gathers facts about the adapter including its ports.
- Updates the properties of an adapter.
- Gather facts about an adapter of a CPC (Z system), including its ports.
- Update the properties of an adapter.



Requirements
------------
The below requirements are needed on the host that executes this module.

- Network access to HMC
- zhmcclient >=0.20.0
- ansible >=2.2.0.0
- Access to the WS API of the HMC of the targeted Z system. The targeted Z system must be in the Dynamic Partition Manager (DPM) operational mode.
- Python package zhmcclient >=0.20.0


Parameters
Expand All @@ -51,10 +50,10 @@ Parameters
</div>
</td>
<td>
<b>Default:</b><br/><div style="color: blue">"Real HMC will be used."</div>
<b>Default:</b><br/><div style="color: blue">null</div>
</td>
<td>
<div>A <code>zhmcclient_mock.FakedSession</code> object that has a mocked HMC set up. If provided, it will be used instead of connecting to a real HMC. This is used for testing purposes only.</div>
<div>A <code>zhmcclient_mock.FakedSession</code> object that has a mocked HMC set up. If not null, this session will be used instead of connecting to the HMC specified in <code>hmc_host</code>. This is used for testing purposes only.</div>
</td>
</tr>
<tr>
Expand All @@ -69,7 +68,7 @@ Parameters
<td>
</td>
<td>
<div>The authentication credentials for the HMC.</div>
<div>The authentication credentials for the HMC, as a dictionary of <code>userid</code>, <code>password</code>.</div>
</td>
</tr>
<tr>
Expand Down Expand Up @@ -146,7 +145,7 @@ Parameters
</div>
</td>
<td>
<b>Default:</b><br/><div style="color: blue">"No match properties"</div>
<b>Default:</b><br/><div style="color: blue">null</div>
</td>
<td>
<div>Only for <code>state=set</code>: Match properties for identifying the target adapter in the set of adapters in the CPC, if an adapter with the name specified in the <code>name</code> module parameter does not exist in that set. This parameter will be ignored otherwise.</div>
Expand Down Expand Up @@ -181,7 +180,7 @@ Parameters
</div>
</td>
<td>
<b>Default:</b><br/><div style="color: blue">"No property changes (other than possibly C(name))."</div>
<b>Default:</b><br/><div style="color: blue">null</div>
</td>
<td>
<div>Only for <code>state=set|present</code>: New values for the properties of the adapter. Properties omitted in this dictionary will remain unchanged. This parameter will be ignored for other states.</div>
Expand Down Expand Up @@ -356,8 +355,8 @@ Status
Authors
~~~~~~~

- Andreas Maier (@andy-maier, maiera@de.ibm.com)
- Andreas Scheuring (@scheuran, scheuran@de.ibm.com)
- Andreas Maier (maiera@de.ibm.com)
- Andreas Scheuring (IBM, at the time)


.. hint::
Expand Down
25 changes: 12 additions & 13 deletions docs/gen/zhmc_cpc_module.rst
View file
Expand Up @@ -5,8 +5,8 @@
.. _zhmc_cpc_module:


zhmc_cpc -- Manages a CPC
+++++++++++++++++++++++++
zhmc_cpc -- Manages Z systems at the system level
+++++++++++++++++++++++++++++++++++++++++++++++++


.. contents::
Expand All @@ -16,18 +16,17 @@ zhmc_cpc -- Manages a CPC

Synopsis
--------
- Gathers facts about the CPC including its child resources.
- Updates the properties of a CPC.
- Gather facts about a CPC (Z system), including its adapters and partitions.
- Update the properties of a CPC.



Requirements
------------
The below requirements are needed on the host that executes this module.

- Network access to HMC
- zhmcclient >=0.20.0
- ansible >=2.2.0.0
- Access to the WS API of the HMC of the targeted Z system. The targeted Z system must be in the Dynamic Partition Manager (DPM) operational mode.
- Python package zhmcclient >=0.20.0


Parameters
Expand All @@ -51,10 +50,10 @@ Parameters
</div>
</td>
<td>
<b>Default:</b><br/><div style="color: blue">"Real HMC will be used."</div>
<b>Default:</b><br/><div style="color: blue">null</div>
</td>
<td>
<div>A <code>zhmcclient_mock.FakedSession</code> object that has a mocked HMC set up. If provided, it will be used instead of connecting to a real HMC. This is used for testing purposes only.</div>
<div>A <code>zhmcclient_mock.FakedSession</code> object that has a mocked HMC set up. If not null, this session will be used instead of connecting to the HMC specified in <code>hmc_host</code>. This is used for testing purposes only.</div>
</td>
</tr>
<tr>
Expand All @@ -69,7 +68,7 @@ Parameters
<td>
</td>
<td>
<div>The authentication credentials for the HMC.</div>
<div>The authentication credentials for the HMC, as a dictionary of <code>userid</code>, <code>password</code>.</div>
</td>
</tr>
<tr>
Expand Down Expand Up @@ -161,7 +160,7 @@ Parameters
</div>
</td>
<td>
<b>Default:</b><br/><div style="color: blue">"No property changes."</div>
<b>Default:</b><br/><div style="color: blue">null</div>
</td>
<td>
<div>Only for <code>state=set</code>: New values for the properties of the CPC. Properties omitted in this dictionary will remain unchanged. This parameter will be ignored for <code>state=facts</code>.</div>
Expand Down Expand Up @@ -299,8 +298,8 @@ Status
Authors
~~~~~~~

- Andreas Maier (@andy-maier, maiera@de.ibm.com)
- Andreas Scheuring (@scheuran, scheuran@de.ibm.com)
- Andreas Maier (maiera@de.ibm.com)
- Andreas Scheuring (IBM, at the time)


.. hint::
Expand Down
31 changes: 12 additions & 19 deletions docs/gen/zhmc_crypto_attachment_module.rst
View file
Expand Up @@ -5,8 +5,8 @@
.. _zhmc_crypto_attachment_module:


zhmc_crypto_attachment -- Manages the attachment of crypto adapters and domains to partitions
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
zhmc_crypto_attachment -- Manages the attachment of crypto resources to partitions of Z systems
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


.. contents::
Expand All @@ -16,19 +16,18 @@ zhmc_crypto_attachment -- Manages the attachment of crypto adapters and domains

Synopsis
--------
- Gathers facts about the attachment of crypto adapters and domains to a partition.
- Attaches a range of crypto domains and a number of crypto adapters to a partition.
- Detaches all crypto domains and all crypto adapters from a partition.
- Gather facts about the attachment of crypto adapters and crypto domains to a partition of a CPC (Z system).
- Attach a range of crypto domains and a number of crypto adapters to a partition.
- Detach all crypto domains and all crypto adapters from a partition.



Requirements
------------
The below requirements are needed on the host that executes this module.

- Network access to HMC
- zhmcclient >=0.20.0
- ansible >=2.2.0.0
- Access to the WS API of the HMC of the targeted Z system. The targeted Z system must be in the Dynamic Partition Manager (DPM) operational mode.
- Python package zhmcclient >=0.20.0


Parameters
Expand Down Expand Up @@ -138,10 +137,10 @@ Parameters
</div>
</td>
<td>
<b>Default:</b><br/><div style="color: blue">"Real HMC will be used."</div>
<b>Default:</b><br/><div style="color: blue">null</div>
</td>
<td>
<div>A <code>zhmcclient_mock.FakedSession</code> object that has a mocked HMC set up. If provided, it will be used instead of connecting to a real HMC. This is used for testing purposes only.</div>
<div>A <code>zhmcclient_mock.FakedSession</code> object that has a mocked HMC set up. If not null, this session will be used instead of connecting to the HMC specified in <code>hmc_host</code>. This is used for testing purposes only.</div>
</td>
</tr>
<tr>
Expand All @@ -156,7 +155,7 @@ Parameters
<td>
</td>
<td>
<div>The authentication credentials for the HMC.</div>
<div>The authentication credentials for the HMC, as a dictionary of <code>userid</code>, <code>password</code>.</div>
</td>
</tr>
<tr>
Expand Down Expand Up @@ -265,12 +264,6 @@ Parameters
<br/>


Notes
-----

.. note::
- The CPC of the target partition must be in the Dynamic Partition Manager (DPM) operational mode.



Examples
Expand Down Expand Up @@ -418,8 +411,8 @@ Status
Authors
~~~~~~~

- Andreas Maier (@andy-maier, maiera@de.ibm.com)
- Andreas Scheuring (@scheuran, scheuran@de.ibm.com)
- Andreas Maier (maiera@de.ibm.com)
- Andreas Scheuring (IBM, at the time)


.. hint::
Expand Down
34 changes: 14 additions & 20 deletions docs/gen/zhmc_hba_module.rst
View file
Expand Up @@ -5,8 +5,8 @@
.. _zhmc_hba_module:


zhmc_hba -- Manages HBAs in existing partitions (without "dpm-storage-management" feature)
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
zhmc_hba -- Manages HBAs in partitions of Z systems
+++++++++++++++++++++++++++++++++++++++++++++++++++


.. contents::
Expand All @@ -16,18 +16,18 @@ zhmc_hba -- Manages HBAs in existing partitions (without "dpm-storage-management

Synopsis
--------
- Creates, updates, and deletes HBAs in existing partitions of a CPC.
- The targeted CPC must be in the Dynamic Partition Manager (DPM) operational mode.
- Create, update, or delete an HBA (virtual Host Bus Adapter) in a partition of a CPC (Z system).
- Note that the Ansible module zhmc_partition can be used to gather facts about existing HBAs of a partition.



Requirements
------------
The below requirements are needed on the host that executes this module.

- Network access to HMC
- zhmcclient >=0.14.0
- ansible >=2.2.0.0
- Access to the WS API of the HMC of the targeted Z system. The targeted Z system must be in the Dynamic Partition Manager (DPM) operational mode.
- The targeted Z system must be a z13 generation. The z14 and later generations manage HBAs automatically via the "dpm-storage-management" firmware feature.
- Python package zhmcclient >=0.14.0


Parameters
Expand Down Expand Up @@ -66,10 +66,10 @@ Parameters
</div>
</td>
<td>
<b>Default:</b><br/><div style="color: blue">"Real HMC will be used."</div>
<b>Default:</b><br/><div style="color: blue">null</div>
</td>
<td>
<div>A <code>zhmcclient_mock.FakedSession</code> object that has a mocked HMC set up. If provided, it will be used instead of connecting to a real HMC. This is used for testing purposes only.</div>
<div>A <code>zhmcclient_mock.FakedSession</code> object that has a mocked HMC set up. If not null, this session will be used instead of connecting to the HMC specified in <code>hmc_host</code>. This is used for testing purposes only.</div>
</td>
</tr>
<tr>
Expand All @@ -84,7 +84,7 @@ Parameters
<td>
</td>
<td>
<div>The authentication credentials for the HMC.</div>
<div>The authentication credentials for the HMC, as a dictionary of <code>userid</code>, <code>password</code>.</div>
</td>
</tr>
<tr>
Expand Down Expand Up @@ -191,7 +191,7 @@ Parameters
</div>
</td>
<td>
<b>Default:</b><br/><div style="color: blue">"No input properties"</div>
<b>Default:</b><br/><div style="color: blue">null</div>
</td>
<td>
<div>Dictionary with input properties for the HBA, for <code>state=present</code>. Key is the property name with underscores instead of hyphens, and value is the property value in YAML syntax. Integer properties may also be provided as decimal strings. Will be ignored for <code>state=absent</code>.</div>
Expand Down Expand Up @@ -228,12 +228,6 @@ Parameters
<br/>


Notes
-----

.. note::
- See also Ansible module zhmc_partition.



Examples
Expand Down Expand Up @@ -329,9 +323,9 @@ Status
Authors
~~~~~~~

- Andreas Maier (@andy-maier, maiera@de.ibm.com)
- Andreas Scheuring (@scheuran, scheuran@de.ibm.com)
- Juergen Leopold (@leopoldjuergen, leopoldj@de.ibm.com)
- Andreas Maier (maiera@de.ibm.com)
- Andreas Scheuring (IBM, at the time)
- Juergen Leopold (IBM, at the time)


.. hint::
Expand Down

0 comments on commit f118011

Please sign in to comment.