Skip to content

Commit

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

* 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.

* Changed cross references to other modules fron note to seealso.

Signed-off-by: Andreas Maier <maiera@de.ibm.com>
  • Loading branch information
@andy-maier
andy-maier committed Sep 21, 2020
1 parent 0672385 commit f4221c2
Show file tree
Hide file tree
Showing 24 changed files with 290 additions and 315 deletions.
5 changes: 5 additions & 0 deletions docs/gen/common_return_values.rst
View file
Expand Up @@ -24,6 +24,11 @@ changed
```````
A boolean indicating if the task had to make changes.

diff
````

Information on differences between the previous and current state. Often a dictionary with entries ``before`` and ``after``, which will then be formatted by the callback plugin to a diff view.

failed
``````
A boolean that indicates if the task was failed or not.
Expand Down
2 changes: 1 addition & 1 deletion docs/gen/modules_support.rst
View file
Expand Up @@ -46,7 +46,7 @@ For development-oriented topics, use the `ansible-devel Google group <https://gr

The modules are hosted on GitHub in a subdirectory of the `Ansible <https://github.com/ansible/ansible/tree/devel/lib/ansible/modules>`_ repo.

NOTE: If you have a Red Hat Ansible Automation product subscription, please follow the standard issue reporting process via the `Red Hat Customer Portal <https:///access.redhat.com/>`_.
NOTE: If you have a Red Hat Ansible Automation product subscription, please follow the standard issue reporting process via the `Red Hat Customer Portal <https://access.redhat.com/>`_.

Support
=======
Expand Down
20 changes: 10 additions & 10 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 Down Expand Up @@ -66,9 +65,10 @@ Parameters
</div>
</td>
<td>
</td>
<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 @@ -83,7 +83,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
20 changes: 10 additions & 10 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,9 +50,10 @@ Parameters
</div>
</td>
<td>
</td>
<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 @@ -68,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
28 changes: 11 additions & 17 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,9 +137,10 @@ Parameters
</div>
</td>
<td>
</td>
<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 @@ -155,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 @@ -264,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
27 changes: 11 additions & 16 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,9 +66,10 @@ Parameters
</div>
</td>
<td>
</td>
<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 @@ -83,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 @@ -227,12 +228,6 @@ Parameters
<br/>


Notes
-----

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



Examples
Expand Down
26 changes: 10 additions & 16 deletions docs/gen/zhmc_nic_module.rst
View file
Expand Up @@ -5,8 +5,8 @@
.. _zhmc_nic_module:


zhmc_nic -- Manages NICs in existing partitions
+++++++++++++++++++++++++++++++++++++++++++++++
zhmc_nic -- Manages NICs in partitions of Z systems
+++++++++++++++++++++++++++++++++++++++++++++++++++


.. contents::
Expand All @@ -16,18 +16,17 @@ zhmc_nic -- Manages NICs in existing partitions

Synopsis
--------
- Creates, updates, and deletes NICs in existing partitions of a CPC.
- The targeted CPC must be in the Dynamic Partition Manager (DPM) operational mode.
- Create, update, or delete a NIC (virtual Network Interface Card) in a partition of a CPC (Z system).
- Note that the Ansible module zhmc_partition can be used to gather facts about existing NICs 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.
- Python package zhmcclient >=0.14.0


Parameters
Expand Down Expand Up @@ -66,9 +65,10 @@ Parameters
</div>
</td>
<td>
</td>
<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 @@ -83,7 +83,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 @@ -227,12 +227,6 @@ Parameters
<br/>


Notes
-----

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



Examples
Expand Down

0 comments on commit f4221c2

Please sign in to comment.