diff --git a/doc/source/backwards-incompatible.rst b/doc/source/backwards-incompatible.rst
index bce8671736..22c300de05 100644
--- a/doc/source/backwards-incompatible.rst
+++ b/doc/source/backwards-incompatible.rst
@@ -57,7 +57,7 @@ Releases Before 3.0
 2. <type> should not be optional for command `openstack service create`
 
   Previously, the command was `openstack service create <name> --type <type>`,
-  whereas now it is: `openstack service create <type> --name <name>`
+  whereas now it is: `openstack service create <type> --name <name>`.
   This bug also affected python-keystoneclient, and keystone.
 
   * In favor of: making <type> a positional argument.
@@ -181,12 +181,12 @@ Releases Before 3.0
   * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1546065
   * Commit: https://review.openstack.org/#/c/281088/
 
-12. <version> <url> <md5hash> should be optional for command `openstack compute agent set`
+12. `<version> <url> <md5hash>` should be optional for command `openstack
+    compute agent set`
 
-  Previously, the command was `openstack compute agent set <id> <version> <url> <md5hash>`,
-  whereas now it is: `openstack compute agent set <id> --version <version>
-                                                       --url <url>
-                                                       --md5hash <md5hash>`.
+  Previously, the command was `openstack compute agent set <id> <version> <url>
+  <md5hash>`, whereas now it is: `openstack compute agent set <id> --version
+  <version> --url <url> --md5hash <md5hash>`.
 
   * In favor of: making <version> <url> <md5hash> optional.
   * As of: NA
diff --git a/doc/source/command-objects/consistency-group-snapshot.rst b/doc/source/command-objects/consistency-group-snapshot.rst
index 3d455038ec..29d5065663 100644
--- a/doc/source/command-objects/consistency-group-snapshot.rst
+++ b/doc/source/command-objects/consistency-group-snapshot.rst
@@ -27,7 +27,7 @@ Create new consistency group snapshot.
     Description of this consistency group snapshot
 
 .. _consistency_group_snapshot_create-snapshot-name:
-.. option:: <snapshot-name>
+.. describe:: <snapshot-name>
 
     Name of new consistency group snapshot (default to None)
 
diff --git a/doc/source/command-objects/consistency-group.rst b/doc/source/command-objects/consistency-group.rst
index 232cf8e4fb..57082c6df8 100644
--- a/doc/source/command-objects/consistency-group.rst
+++ b/doc/source/command-objects/consistency-group.rst
@@ -62,7 +62,7 @@ Create new consistency group.
     (not available if creating consistency group from source)
 
 .. _consistency_group_create-name:
-.. option:: <name>
+.. describe:: <name>
 
     Name of new consistency group (default to None)
 
diff --git a/doc/source/command-objects/endpoint.rst b/doc/source/command-objects/endpoint.rst
index b98055a1df..02a75bea1f 100644
--- a/doc/source/command-objects/endpoint.rst
+++ b/doc/source/command-objects/endpoint.rst
@@ -11,7 +11,7 @@ Create new endpoint
 
 *Identity version 2 only*
 
-.. program:: endpoint create
+.. program:: endpoint create (v2)
 .. code:: bash
 
     openstack endpoint create
@@ -44,7 +44,7 @@ Create new endpoint
 
 *Identity version 3 only*
 
-.. program:: endpoint create
+.. program:: endpoint create (v3)
 .. code:: bash
 
     openstack endpoint create
diff --git a/doc/source/command-objects/volume.rst b/doc/source/command-objects/volume.rst
index 67598e63c3..85a920ebab 100644
--- a/doc/source/command-objects/volume.rst
+++ b/doc/source/command-objects/volume.rst
@@ -37,18 +37,18 @@ Create new volume
 
     Set the type of volume
 
-    Select :option:`\<volume-type\>` from the available types as shown
+    Select ``<volume-type>`` from the available types as shown
     by ``volume type list``.
 
 .. option:: --image <image>
 
-    Use :option:`\<image\>` as source of volume (name or ID)
+    Use ``<image>`` as source of volume (name or ID)
 
     This is commonly used to create a boot volume for a server.
 
 .. option:: --snapshot <snapshot>
 
-    Use :option:`\<snapshot\>` as source of volume (name or ID)
+    Use ``<snapshot>`` as source of volume (name or ID)
 
 .. option:: --source <volume>
 
@@ -72,7 +72,7 @@ Create new volume
 
 .. option:: --availability-zone <availability-zone>
 
-    Create volume in :option:`\<availability-zone\>`
+    Create volume in ``<availability-zone>``
 
 .. option:: --consistency-group <consistency-group>
 
@@ -163,7 +163,7 @@ List volumes
 
 .. option:: --project <project>
 
-    Filter results by :option:`\<project\>` (name or ID) (admin only)
+    Filter results by ``<project>`` (name or ID) (admin only)
 
     *Volume version 2 only*
 
@@ -177,7 +177,7 @@ List volumes
 
 .. option:: --user <user>
 
-    Filter results by :option:`\<user\>` (name or ID) (admin only)
+    Filter results by ``<user>`` (name or ID) (admin only)
 
     *Volume version 2 only*
 
@@ -337,8 +337,8 @@ Set volume properties
     (repeat option to set multiple image properties)
 
     Image properties are copied along with the image when creating a volume
-    using :option:`--image`.  Note that these properties are immutable on the
-    image itself, this option updates the copy attached to this volume.
+    using ``--image``.  Note that these properties are immutable on the image
+    itself, this option updates the copy attached to this volume.
 
     *Volume version 2 only*
 
diff --git a/doc/source/command-options.rst b/doc/source/command-options.rst
index faa82bee21..8d1d1c4e69 100644
--- a/doc/source/command-options.rst
+++ b/doc/source/command-options.rst
@@ -16,9 +16,10 @@ new command without understanding why or why not that instance is correct.
 
 The :doc:`Human Interface Guide <humaninterfaceguide>`
 describes the guildelines for option names and usage.  In short:
-  * All option names shall be GNU-style long names (two leading dashes).
-  * Some global options may have short names, generally limited to those defined
-    in support libraries such as ``cliff``.
+
+* All option names shall be GNU-style long names (two leading dashes).
+* Some global options may have short names, generally limited to those defined
+  in support libraries such as ``cliff``.
 
 General Command Options
 =======================
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 6af49c52f0..ae0ee0ffb5 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -57,6 +57,7 @@ Developer Documentation
    command-errors
    command-logs
    specs/commands
+   api/modules
 
 Project Goals
 -------------
@@ -92,5 +93,4 @@ Indices and Tables
 ==================
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
diff --git a/doc/source/man/openstack.rst b/doc/source/man/openstack.rst
index 5793c6ee85..3021ef8756 100644
--- a/doc/source/man/openstack.rst
+++ b/doc/source/man/openstack.rst
@@ -58,95 +58,146 @@ OPTIONS
 
 :program:`openstack` recognizes the following global options:
 
-:option:`--os-cloud` <cloud-name>
+.. option:: --os-cloud <cloud-name>
+
     :program:`openstack` will look for a ``clouds.yaml`` file that contains
     a cloud configuration to use for authentication.  See CLOUD CONFIGURATION
     below for more information.
 
-:option:`--os-auth-type` <auth-type>
+.. option::  --os-auth-type <auth-type>
+
     The authentication plugin type to use when connecting to the Identity service.
+
     If this option is not set, :program:`openstack` will attempt to guess the
     authentication method to use based on the other options.
-    If this option is set, its version must match :option:`--os-identity-api-version`
 
-:option:`--os-auth-url` <auth-url>
+    If this option is set, its version must match
+    :option:`--os-identity-api-version`
+
+.. option:: --os-auth-url <auth-url>
+
     Authentication URL
 
-:option:`--os-url` <service-url>
+.. option:: --os-url <service-url>
+
     Service URL, when using a service token for authentication
 
-:option:`--os-domain-name` <auth-domain-name> | :option:`--os-domain-id` <auth-domain-id>
-    Domain-level authorization scope (name or ID)
+.. option:: --os-domain-name <auth-domain-name>
 
-:option:`--os-project-name` <auth-project-name> | :option:`--os-project-id` <auth-project-id>
-    Project-level authentication scope (name or ID)
+    Domain-level authorization scope (by name)
 
-:option:`--os-project-domain-name` <auth-project-domain-name> | :option:`--os-project-domain-id` <auth-project-domain-id>
-    Domain name or ID containing project
+.. option:: --os-domain-id <auth-domain-id>
+
+    Domain-level authorization scope (by ID)
+
+.. option:: --os-project-name <auth-project-name>
+
+    Project-level authentication scope (by name)
+
+.. option:: --os-project-id <auth-project-id>
+
+    Project-level authentication scope (by ID)
+
+.. option:: --os-project-domain-name <auth-project-domain-name>
+
+    Domain name containing project
+
+.. option:: --os-project-domain-id <auth-project-domain-id>
+
+    Domain ID containing project
+
+.. option:: --os-username <auth-username>
 
-:option:`--os-username` <auth-username>
     Authentication username
 
-:option:`--os-password` <auth-password>
+.. option:: --os-password <auth-password>
+
     Authentication password
 
-:option:`--os-token` <token>
+.. option:: --os-token <token>
+
     Authenticated token or service token
 
-:option:`--os-user-domain-name` <auth-user-domain-name> | :option:`--os-user-domain-id` <auth-user-domain-id>
-    Domain name or ID containing user
+.. option:: --os-user-domain-name <auth-user-domain-name>
+
+    Domain name containing user
+
+.. option:: --os-user-domain-id <auth-user-domain-id>
+
+    Domain ID containing user
+
+.. option:: --os-trust-id <trust-id>
 
-:option:`--os-trust-id` <trust-id>
     ID of the trust to use as a trustee user
 
-:option:`--os-default-domain` <auth-domain>
+.. option:: --os-default-domain <auth-domain>
+
     Default domain ID (Default: 'default')
 
-:option:`--os-region-name` <auth-region-name>
+.. option:: --os-region-name <auth-region-name>
+
     Authentication region name
 
-:option:`--os-cacert` <ca-bundle-file>
+.. option:: --os-cacert <ca-bundle-file>
+
     CA certificate bundle file
 
-:option:`--verify` | :option:`--insecure`
+.. option:: --verify` | :option:`--insecure
+
     Verify or ignore server certificate (default: verify)
 
-:option:`--os-cert` <certificate-file>
+.. option:: --os-cert <certificate-file>
+
     Client certificate bundle file
 
-:option:`--os-key` <key-file>
+.. option:: --os-key <key-file>
+
     Client certificate key file
 
-:option:`--os-identity-api-version` <identity-api-version>
+.. option:: --os-identity-api-version <identity-api-version>
+
     Identity API version (Default: 2.0)
 
-:option:`--os-XXXX-api-version` <XXXX-api-version>
-    Additional API version options will be available depending on the installed API libraries.
+.. option:: --os-XXXX-api-version <XXXX-api-version>
+
+    Additional API version options will be available depending on the installed
+    API libraries.
+
+.. option:: --os-interface <interface>
 
-:option:`--os-interface` <interface>
     Interface type. Valid options are `public`, `admin` and `internal`.
 
-:option:`--os-profile` <hmac-key>
+.. option:: --os-profile <hmac-key>
+
     Performance profiling HMAC key for encrypting context data
 
     This key should be the value of one of the HMAC keys defined in the
     configuration files of OpenStack services to be traced.
 
-:option:`--os-beta-command`
+.. option:: --os-beta-command
+
     Enable beta commands which are subject to change
 
-:option:`--log-file` <LOGFILE>
+.. option:: --log-file <LOGFILE>
+
     Specify a file to log output. Disabled by default.
 
-:option:`-v, --verbose`
+.. option:: -v, --verbose
+
     Increase verbosity of output. Can be repeated.
 
-:option:`-q, --quiet`
+.. option:: -q, --quiet
+
     Suppress output except warnings and errors
 
-:option:`--debug`
+.. option:: --debug
+
     Show tracebacks on errors and set verbosity to debug
 
+.. option:: --help
+
+    Show help message and exit
+
 COMMANDS
 ========
 
@@ -160,14 +211,16 @@ To get a description of a specific command::
 
 Note that the set of commands shown will vary depending on the API versions
 that are in effect at that time.  For example, to force the display of the
-Identity v3 commands:
+Identity v3 commands::
 
     openstack --os-identity-api-version 3 --help
 
-:option:`complete`
+.. option:: complete
+
     Print the bash completion functions for the current command set.
 
-:option:`help <command>`
+.. option:: help <command>
+
     Print help for an individual command
 
 Additional information on the OpenStackClient command structure and arguments
@@ -328,64 +381,85 @@ ENVIRONMENT VARIABLES
 
 The following environment variables can be set to alter the behaviour of :program:`openstack`.  Most of them have corresponding command-line options that take precedence if set.
 
-:envvar:`OS_CLOUD`
+.. envvar:: OS_CLOUD
+
     The name of a cloud configuration in ``clouds.yaml``.
 
-:envvar:`OS_AUTH_PLUGIN`
+.. envvar:: OS_AUTH_PLUGIN
+
     The authentication plugin to use when connecting to the Identity service, its version must match the Identity API version
 
-:envvar:`OS_AUTH_URL`
+.. envvar:: OS_AUTH_URL
+
     Authentication URL
 
-:envvar:`OS_URL`
+.. envvar:: OS_URL
+
     Service URL (when using the service token)
 
-:envvar:`OS_DOMAIN_NAME`
+.. envvar:: OS_DOMAIN_NAME
+
     Domain-level authorization scope (name or ID)
 
-:envvar:`OS_PROJECT_NAME`
+.. envvar:: OS_PROJECT_NAME
+
     Project-level authentication scope (name or ID)
 
-:envvar:`OS_PROJECT_DOMAIN_NAME`
+.. envvar:: OS_PROJECT_DOMAIN_NAME
+
     Domain name or ID containing project
 
-:envvar:`OS_USERNAME`
+.. envvar:: OS_USERNAME
+
     Authentication username
 
-:envvar:`OS_TOKEN`
+.. envvar:: OS_TOKEN
+
     Authenticated or service token
 
-:envvar:`OS_PASSWORD`
+.. envvar:: OS_PASSWORD
+
     Authentication password
 
-:envvar:`OS_USER_DOMAIN_NAME`
+.. envvar:: OS_USER_DOMAIN_NAME
+
     Domain name or ID containing user
 
-:envvar:`OS_TRUST_ID`
+.. envvar:: OS_TRUST_ID
+
     ID of the trust to use as a trustee user
 
-:envvar:`OS_DEFAULT_DOMAIN`
+.. envvar:: OS_DEFAULT_DOMAIN
+
     Default domain ID (Default: 'default')
 
-:envvar:`OS_REGION_NAME`
+.. envvar:: OS_REGION_NAME
+
     Authentication region name
 
-:envvar:`OS_CACERT`
+.. envvar:: OS_CACERT
+
     CA certificate bundle file
 
-:envvar:`OS_CERT`
+.. envvar:: OS_CERT
+
     Client certificate bundle file
 
-:envvar:`OS_KEY`
+.. envvar:: OS_KEY
+
     Client certificate key file
 
-:envvar:`OS_IDENTITY_API_VERSION`
+.. envvar:: OS_IDENTITY_API_VERSION
+
     Identity API version (Default: 2.0)
 
-:envvar:`OS_XXXX_API_VERSION`
-    Additional API version options will be available depending on the installed API libraries.
+.. envvar:: OS_XXXX_API_VERSION
+
+    Additional API version options will be available depending on the installed
+    API libraries.
+
+.. envvar:: OS_INTERFACE
 
-:envvar:`OS_INTERFACE`
     Interface type. Valid options are `public`, `admin` and `internal`.
 
 
diff --git a/doc/source/plugin-commands.rst b/doc/source/plugin-commands.rst
index 182f5392c6..69d31c22b3 100644
--- a/doc/source/plugin-commands.rst
+++ b/doc/source/plugin-commands.rst
@@ -62,11 +62,10 @@ mistral
 .. list-plugins:: openstack.workflow_engine.v2
    :detailed:
 
-murano
-------
-
-.. list-plugins:: openstack.application_catalog.v1
-   :detailed:
+.. murano
+.. # the murano docs cause warnings and a broken docs build
+.. # .. list-plugins:: openstack.application_catalog.v1
+.. #   :detailed:
 
 neutron
 -------
diff --git a/doc/source/specs/commands.rst b/doc/source/specs/commands.rst
index 55bf947651..5ae0e84069 100644
--- a/doc/source/specs/commands.rst
+++ b/doc/source/specs/commands.rst
@@ -19,14 +19,15 @@ Objects Specs
 
 Add specifications for new objects based on the ``example`` object.
 
-* ``example``: (**example API name**) example object description
-
 Actions Specs
 -------------
 
 Add specifications for new actions based on the ``example`` action.
 
-* ``example`` - example action description
+.. toctree::
+   :maxdepth: 1
+
+   network-topology
 
 Commands Specs
 --------------
diff --git a/doc/source/specs/network-topology.rst b/doc/source/specs/network-topology.rst
index a0218a1e1b..6789ee975f 100755
--- a/doc/source/specs/network-topology.rst
+++ b/doc/source/specs/network-topology.rst
@@ -38,7 +38,7 @@ Show network topology details
     openstack network topology show
         <network>
 
-.. _network_topology_show-network
+.. _network_topology_show-network:
 .. describe:: <network>
 
     Show network topology for a specific network (name or ID)
diff --git a/openstackclient/compute/client.py b/openstackclient/compute/client.py
index c5b364b238..b4b463b412 100644
--- a/openstackclient/compute/client.py
+++ b/openstackclient/compute/client.py
@@ -96,6 +96,7 @@ def check_api_version(check_version):
     """Validate version supplied by user
 
     Returns:
+
     * True if version is OK
     * False if the version has not been checked and the previous plugin
       check should be performed
diff --git a/openstackclient/tests/unit/identity/v3/fakes.py b/openstackclient/tests/unit/identity/v3/fakes.py
index 139d90d5b8..291f977d4e 100644
--- a/openstackclient/tests/unit/identity/v3/fakes.py
+++ b/openstackclient/tests/unit/identity/v3/fakes.py
@@ -729,7 +729,7 @@ class FakeCredential(object):
             A list of FakeResource objects faking credentials
         :param Integer count:
             The number of credentials to be faked
-        :return
+        :return:
             An iterable Mock object with side_effect set to a list of faked
             credentials
         """
@@ -867,7 +867,7 @@ class FakeGroup(object):
             A list of FakeResource objects faking groups
         :param Integer count:
             The number of groups to be faked
-        :return
+        :return:
             An iterable Mock object with side_effect set to a list of faked
             groups
         """
diff --git a/openstackclient/tests/unit/image/v2/fakes.py b/openstackclient/tests/unit/image/v2/fakes.py
index 8e2f587d29..7f3f02df1f 100644
--- a/openstackclient/tests/unit/image/v2/fakes.py
+++ b/openstackclient/tests/unit/image/v2/fakes.py
@@ -238,7 +238,7 @@ class FakeImage(object):
             A list of FakeResource objects faking images
         :param Integer count:
             The number of images to be faked
-        :return
+        :return:
             An iterable Mock object with side_effect set to a list of faked
             images
         """
@@ -253,7 +253,7 @@ class FakeImage(object):
 
         :param image:
             A FakeResource objects faking image
-        :return
+        :return:
             A tuple which may include the following keys:
             ('id', 'name', 'owner', 'protected', 'visibility', 'tags')
         """
@@ -267,7 +267,7 @@ class FakeImage(object):
 
         :param image:
             A FakeResource objects faking image
-        :return
+        :return:
             A tuple which may include the following values:
             ('image-123', 'image-foo', 'admin', False, 'public', 'bar, baz')
         """