Fix warnings on doc builds

In the sphinx config, mock out the nova imports we do for the
compute manager so the docs will build with fewer errors.

Exclude the alembic migration environment from autodoc.

Fix the remaining markup errors, which are now easier to spot
given the other fixes.

Note that this leaves one remaining warning, which is that the
generated API documentation isn't currently included in a
toctree. This is easy to fix but it would be good to discuss
whether/where to include it in the documentation hierarchy.

Closes-Bug: 1277282
Change-Id: Iee5fc3eeb95a09198d5234d0ea05e150ab26f16b

doc/source/conf.py

@@ -57,6 +57,13 @@ add_module_names = True
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
+# NOTE(cinerama): mock out nova modules so docs can build without warnings
+import mock
+import sys
+MOCK_MODULES = ['nova', 'nova.compute', 'nova.context']
+for module in MOCK_MODULES:
+    sys.modules[module] = mock.Mock()
+
 # -- Options for HTML output --------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with

ironic/drivers/agent.py

@@ -114,7 +114,7 @@ class AgentAndUcsDriver(base.BaseDriver):
 
     This driver implements the `core` functionality, combining
     :class:ironic.drivers.modules.ucs.power.Power for power
-        on/off and reboot with
+    on/off and reboot with
     :class:'ironic.driver.modules.agent.AgentDeploy' (for image deployment.)
     Implementations are in those respective classes;
     this class is merely the glue between them.

ironic/drivers/base.py

@@ -368,10 +368,12 @@ class BootInterface(object):
         :param ramdisk_params: the options to be passed to the ironic ramdisk.
             Different implementations might want to boot the ramdisk in
             different ways by passing parameters to them.  For example,
-            * When DIB ramdisk is booted to deploy a node, it takes the
+
+            - When DIB ramdisk is booted to deploy a node, it takes the
               parameters iscsi_target_iqn, deployment_id, ironic_api_url, etc.
-            * When Agent ramdisk is booted to deploy a node, it takes the
+            - When Agent ramdisk is booted to deploy a node, it takes the
               parameters ipa-driver-name, ipa-api-url, root_device, etc.
+
             Other implementations can make use of ramdisk_params to pass such
             information.  Different implementations of boot interface will
             have different ways of passing parameters to the ramdisk.

ironic/drivers/modules/irmc/deploy.py

@@ -790,6 +790,7 @@ class VendorPassthru(agent_base_vendor.BaseAgentVendor):
         :param task: A TaskManager object.
         :param kwargs: The arguments sent with vendor passthru.  The expected
             kwargs are::
+
                 'key': The deploy key for authorization
                 'status': 'SUCCEEDED' or 'FAILED'
                 'error': The error message if status == 'FAILED'
@@ -811,6 +812,7 @@ class VendorPassthru(agent_base_vendor.BaseAgentVendor):
         This method continues the iSCSI deployment from the conductor node
         and writes the deploy image to the bare metal's disk.  After that,
         it does the following depending on boot_option for deploy:
+
         - If the boot_option requested for this deploy is 'local', then it
           sets the node to boot from disk (ramdisk installs the boot loader
           present within the image to the bare metal's disk).

setup.cfg

@@ -80,6 +80,9 @@ ironic.database.migration_backend =
 
 [pbr]
 autodoc_index_modules = True
+autodoc_exclude_modules =
+    ironic.db.sqlalchemy.alembic.env
+    ironic.db.sqlalchemy.alembic.versions.*
 
 [build_sphinx]
 all_files = 1