doc: Correct Sphinx warnings

- Fix option-describe typos
- Correct option and envvar markup, for commands that are using the
  reference form instead of the definition form or are marking up
  option arguments as options
- Avoid duplicate commands
- Fix some invalid docstrings
- Fix some invalid indentation
- Disable the murano plugin, which has invalid docs
- Correct issues with- and track the network-topology spec
- Include API modules in docs

Change-Id: I3d5ed5e872540fe13f3e4bd5e9335829dc9a5226

Author: stephenfin

doc/source/backwards-incompatible.rst

@@ -46,7 +46,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.
@@ -170,12 +170,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

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)
 

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)
 

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

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*
 

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
 =======================

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`