Skip to content

Commit

Permalink
Docs: Fixed links and semantic markup
Browse files Browse the repository at this point in the history 
Details:

* Fixed broken links to glossary terms, e.g. for 'HMC API' book.

* Fixed broken links to Ansible modules, e.g. zhmc_session.

* Changed use of C() or quotes to use semantic markup with O(), RV(), and V().

Signed-off-by: Andreas Maier <[email protected]>
  • Loading branch information
@andy-maier
andy-maier committed Jul 6, 2024
1 parent 4d8bfbd commit 4aeeedd
Show file tree
Hide file tree
Showing 60 changed files with 816 additions and 755 deletions.
2 changes: 2 additions & 0 deletions docs/source/bibliography.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,8 @@ Resources

.. glossary::

.. _`HMC API`:

HMC API
The Web Services API of the z Systems Hardware Management Console, described in the following books:

Expand Down
2 changes: 1 addition & 1 deletion docs/source/installation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -278,7 +278,7 @@ need to be opened:
* 61612 (TCP) - for the HMC API message broker via JMS over STOMP

For details, see sections "Connecting to the API HTTP server" and
"Connecting to the API message broker" in the :term:`HMC API` book.
"Connecting to the API message broker" in the :ref:`HMC API <HMC API>` book.


.. _`Supported environments`:
Expand Down
18 changes: 9 additions & 9 deletions docs/source/modules/zhmc_adapter.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,35 +52,35 @@ hmc_auth

userid
The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ .
The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ .

| **required**: False
| **type**: str

password
The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ .
The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ .

| **required**: False
| **type**: str

session_id
HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`.
HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module <zhmc_session_module>`\ .

| **required**: False
| **type**: str

ca_certs
Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate.
Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate.

| **required**: False
| **type**: str

verify
If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate.
If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate.

| **required**: False
| **type**: bool
Expand Down Expand Up @@ -142,9 +142,9 @@ properties

\* \ :literal:`name`\ : Cannot be specified as a property because the name has already been specified in the \ :literal:`name`\ module parameter.

\* \ :literal:`type`\ : The desired adapter type can be specified in order to support adapters that can change their type (e.g. the FICON Express adapter can change its type between 'not-configured', 'fcp' and 'fc').
\* \ :literal:`type`\ : The desired adapter type can be specified in order to support adapters that can change their type (e.g. the FICON Express adapter can change its type between \ :literal:`not-configured`\ , \ :literal:`fcp`\ and \ :literal:`fc`\ ).

\* \ :literal:`crypto\_type`\ : The crypto type can be specified in order to support the ability of the Crypto Express adapters to change their crypto type. Valid values are 'ep11', 'cca' and 'acc'. Changing to 'acc' will zeroize the crypto adapter.
\* \ :literal:`crypto\_type`\ : The crypto type can be specified in order to support the ability of the Crypto Express adapters to change their crypto type. Valid values are \ :literal:`ep11`\ , \ :literal:`cca`\ and \ :literal:`acc`\ . Changing to \ :literal:`acc`\ will zeroize the crypto adapter.

| **required**: False
| **type**: dict
Expand Down Expand Up @@ -309,7 +309,7 @@ adapter
| **type**: str
{property}
Additional properties of the adapter, as described in the data model of the 'Adapter' object in the :term:\`HMC API\` book. The property names have hyphens (-) as described in that book.
Additional properties of the adapter, as described in the data model of the 'Adapter' object in the \ :ref:`HMC API <HMC API>`\ book. The property names have hyphens (-) as described in that book.

| **type**: raw
Expand All @@ -325,7 +325,7 @@ adapter
| **type**: str
{property}
Additional properties of the port, as described in the data model of the 'Network Port' or 'Storage Port' element object of the 'Adapter' object in the :term:\`HMC API\` book. The property names have hyphens (-) as described in that book. In case of unconfigured FICON adapters, the property list is short.
Additional properties of the port, as described in the data model of the 'Network Port' or 'Storage Port' element object of the 'Adapter' object in the \ :ref:`HMC API <HMC API>`\ book. The property names have hyphens (-) as described in that book. In case of unconfigured FICON adapters, the property list is short.

| **type**: raw
Expand Down
12 changes: 6 additions & 6 deletions docs/source/modules/zhmc_adapter_list.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,35 +51,35 @@ hmc_auth

userid
The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ .
The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ .

| **required**: False
| **type**: str

password
The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ .
The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ .

| **required**: False
| **type**: str

session_id
HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`.
HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module <zhmc_session_module>`\ .

| **required**: False
| **type**: str

ca_certs
Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate.
Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate.

| **required**: False
| **type**: str

verify
If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate.
If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate.

| **required**: False
| **type**: bool
Expand Down Expand Up @@ -227,7 +227,7 @@ msg
| **type**: str
adapters
The list of adapters, with a subset of their properties. For details on the properties, see the data model of the 'Adapter' resource (see :term:\`HMC API\`)
The list of adapters, with a subset of their properties. For details on the properties, see the data model of the 'Adapter' resource (see \ :ref:`HMC API <HMC API>`\ )

| **returned**: success
| **type**: list
Expand Down
22 changes: 11 additions & 11 deletions docs/source/modules/zhmc_console.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,35 +50,35 @@ hmc_auth

userid
The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ .
The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ .

| **required**: False
| **type**: str

password
The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ .
The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ .

| **required**: False
| **type**: str

session_id
HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`.
HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module <zhmc_session_module>`\ .

| **required**: False
| **type**: str

ca_certs
Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate.
Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate.

| **required**: False
| **type**: str

verify
If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate.
If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate.

| **required**: False
| **type**: bool
Expand All @@ -99,7 +99,7 @@ state

bundle_level
Name of the bundle to be installed on the HMC (e.g. 'H71')
Name of the bundle to be installed on the HMC (e.g. \ :literal:`H71`\ )

Required for \ :literal:`state=upgrade`\

Expand All @@ -118,11 +118,11 @@ upgrade_timeout
backup_location_type
Type of backup location for the HMC backup that is performed:

\* 'ftp': The FTP server that was used for the last console backup as defined on the 'Configure Backup Settings' user interface task in the HMC GUI.
\* \ :literal:`ftp`\ : The FTP server that was used for the last console backup as defined on the 'Configure Backup Settings' user interface task in the HMC GUI.

\* 'usb': The USB storage device mounted to the HMC.
\* \ :literal:`usb`\ : The USB storage device mounted to the HMC.

Optional for \ :literal:`state=upgrade`\ , default: 'usb'
Optional for \ :literal:`state=upgrade`\ , default: \ :literal:`usb`\

| **required**: False
| **type**: str
Expand Down Expand Up @@ -222,7 +222,7 @@ hmc
| **type**: str
{property}
Additional properties of the Console object representing the targeted HMC, as described in the data model of the 'Console' object in the :term:\`HMC API\` book. Note that the set of properties has been extended over the past HMC versions, so you will get less properties on older HMC versions. The property names have hyphens (-) as described in that book.
Additional properties of the Console object representing the targeted HMC, as described in the data model of the 'Console' object in the \ :ref:`HMC API <HMC API>`\ book. Note that the set of properties has been extended over the past HMC versions, so you will get less properties on older HMC versions. The property names have hyphens (-) as described in that book.

| **type**: raw
Expand All @@ -232,7 +232,7 @@ hmc
| **type**: dict
{property}
The properties returned from the 'Query API Version' operation, as described in the :term:\`HMC API\` book. Note that the set of properties has been extended over the past HMC versions, so you will get less properties on older HMC versions. The property names have hyphens (-) as described in that book.
The properties returned from the 'Query API Version' operation, as described in the \ :ref:`HMC API <HMC API>`\ book. Note that the set of properties has been extended over the past HMC versions, so you will get less properties on older HMC versions. The property names have hyphens (-) as described in that book.

| **type**: raw
Expand Down
20 changes: 10 additions & 10 deletions docs/source/modules/zhmc_cpc.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,35 +53,35 @@ hmc_auth

userid
The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ .
The userid (username) for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ .

| **required**: False
| **type**: str

password
The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`session\_id`\ .
The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ .

| **required**: False
| **type**: str

session_id
HMC session ID to be used. This is mutually exclusive with providing \ :literal:`userid`\ and \ :literal:`password`\ and can be created as described in :ref:\`zhmc\_session\_module\`.
HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\ and \ :literal:`hmc\_auth.password`\ and can be created as described in the \ :ref:`zhmc\_session module <zhmc_session_module>`\ .

| **required**: False
| **type**: str

ca_certs
Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS\_CA\_BUNDLE' environment variable or the path name in the 'CURL\_CA\_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate.
Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the \ :envvar:`REQUESTS\_CA\_BUNDLE`\ environment variable or the path name in the \ :envvar:`CURL\_CA\_BUNDLE`\ environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate.

| **required**: False
| **type**: str

verify
If True (default), verify the HMC certificate as specified in the \ :literal:`ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`ca\_certs`\ parameter and do not verify the HMC certificate.
If True (default), verify the HMC certificate as specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter. If False, ignore what is specified in the \ :literal:`hmc\_auth.ca\_certs`\ parameter and do not verify the HMC certificate.

| **required**: False
| **type**: bool
Expand Down Expand Up @@ -155,7 +155,7 @@ properties

bundle_level
Name of the bundle to be installed on the SE of the CPC (e.g. 'S71')
Name of the bundle to be installed on the SE of the CPC (e.g. \ :literal:`S71`\ )

Required for \ :literal:`state=upgrade`\

Expand Down Expand Up @@ -339,12 +339,12 @@ cpc
| **type**: str
{property}
Additional properties of the CPC, as described in the data model of the 'CPC' object in the :term:\`HMC API\` book. The property names have hyphens (-) as described in that book.
Additional properties of the CPC, as described in the data model of the 'CPC' object in the \ :ref:`HMC API <HMC API>`\ book. The property names have hyphens (-) as described in that book.

| **type**: raw
adapters
The adapters of the CPC, with a subset of their properties. For details, see the :term:\`HMC API\` book.
The adapters of the CPC, with a subset of their properties. For details, see the \ :ref:`HMC API <HMC API>`\ book.

| **type**: list
| **elements**: dict
Expand Down Expand Up @@ -381,7 +381,7 @@ cpc

partitions
The defined partitions of the CPC, with a subset of their properties. For details, see the :term:\`HMC API\` book.
The defined partitions of the CPC, with a subset of their properties. For details, see the \ :ref:`HMC API <HMC API>`\ book.

| **type**: list
| **elements**: dict
Expand All @@ -408,7 +408,7 @@ cpc

storage-groups
The storage groups associated with the CPC, with a subset of their properties. For details, see the :term:\`HMC API\` book.
The storage groups associated with the CPC, with a subset of their properties. For details, see the \ :ref:`HMC API <HMC API>`\ book.

| **type**: list
| **elements**: dict
Expand Down
Loading

0 comments on commit 4aeeedd

Please sign in to comment.