From 8b24bf766d13ddf556f9df81a9a7b541fa3b49f4 Mon Sep 17 00:00:00 2001 From: Matt Riedemann Date: Mon, 6 Jul 2015 15:18:59 -0700 Subject: [PATCH] Set autodoc_index_modules=True so tox -e docs builds module docs again Commit bd7e62f796fe951fd42c2edad56e252a0b7393c8 disabled the autodoc_index_modules flag for building docs but it wasn't really necessary, that change was just to get the module index out of the main docs page. We want to autodoc the modules so we can view the actual module index in the tox -d docs build results, which also tells us if we have correct ReST format in doc strings. Notes ----- 1. Several doc string blocks have to be fixed as part of this to get the docs tox job to pass. 2. A docstring in vhdutilsv2 is updated to remove the math directive since that requires the sphinx.ext.pngmath extension which requires latex and dvipng packages from the distro - which is overkill for what the docstring was actually doing with the math directive. 3. We exclude autodoc for tests since we don't really care about docstrings on unit tests. 4. We exclude the nova.wsgi.nova-* modules since those won't build with autodoc since they can't be imported (there is no nova/wsgi/__init__.py module). We could arguably add the __init__.py but it's not really necessary for what those scripts are used for. 5. The sphinx.ext.ifconfig extension is removed since there are no docs that use the ifconfig directive. 6. Update the developer docs to explicitly point out that graphviz must be installed prior to running tox -e docs. 7. Hide doc/source/api/autoindex.rst from the toctree so that we don't regress the point of commit bd7e62f796fe951fd42c2edad56e252a0b7393c8. 8. unused_docs and exclude_trees options are removed from conf.py since they are deprecated in Sphinx 1.2.3: https://github.com/sphinx-doc/sphinx/blob/1.2.3/sphinx/config.py#L54 9. Fix imports for moved libvirt volume options. Closes-Bug: #1471934 Change-Id: I946e2f89f2c9fc70e870faaf84e4a8b0fc703344 --- doc/source/conf.py | 14 ++++----- doc/source/development.environment.rst | 2 ++ doc/source/index.rst | 10 +++++++ nova/compute/monitors/base.py | 3 +- nova/network/neutronv2/api.py | 10 ++++--- nova/objects/base.py | 11 +++---- nova/objects/image_meta.py | 2 +- nova/safe_utils.py | 4 +-- .../functional/wsgi/test_flavor_manage.py | 26 ++++++++-------- nova/utils.py | 30 +++++++++++-------- nova/virt/driver.py | 14 ++++----- nova/virt/hyperv/vhdutilsv2.py | 7 ++--- nova/virt/libvirt/driver.py | 12 ++++---- nova/virt/libvirt/host.py | 5 ++-- nova/virt/opts.py | 8 ++--- setup.cfg | 11 ++++++- 16 files changed, 99 insertions(+), 70 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 0c0ce50360c7..dcb375610546 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -30,8 +30,6 @@ sys.path.insert(0, os.path.abspath('./')) extensions = ['sphinx.ext.autodoc', 'ext.nova_todo', 'sphinx.ext.coverage', - 'sphinx.ext.pngmath', - 'sphinx.ext.ifconfig', 'sphinx.ext.graphviz', 'oslosphinx', "ext.support_matrix", @@ -73,14 +71,14 @@ version = version_info.version_string() # Else, today_fmt is used as the format for a strftime call. #today_fmt = '%B %d, %Y' -# List of documents that shouldn't be included in the build. -unused_docs = [ +# A list of glob-style patterns that should be excluded when looking for +# source files. They are matched against the source file names relative to the +# source directory, using slashes as directory separators on all platforms. +exclude_patterns = [ + 'api/nova.wsgi.nova-*', + 'api/nova.tests.*', ] -# List of directories, relative to source directory, that shouldn't be searched -# for source files. -exclude_trees = [] - # The reST default role (used for this markup: `text`) to use # for all documents. #default_role = None diff --git a/doc/source/development.environment.rst b/doc/source/development.environment.rst index 52a674dbed62..787d4fee33f3 100644 --- a/doc/source/development.environment.rst +++ b/doc/source/development.environment.rst @@ -127,6 +127,8 @@ Grab the code from git:: Building the Documentation ========================== +Install the prerequisite packages: graphviz + To do a full documentation build, issue the following command while the nova directory is current. diff --git a/doc/source/index.rst b/doc/source/index.rst index f17bc6b9bf84..b65079d16fb2 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -190,6 +190,16 @@ Module Reference services + +.. # NOTE(mriedem): This is the section where we hide things that we don't + # actually want in the table of contents but sphinx build would fail if + # they aren't in the toctree somewhere. For example, we hide api/autoindex + # since that's already covered with modindex below. +.. toctree:: + :hidden: + + api/autoindex + Indices and tables ================== diff --git a/nova/compute/monitors/base.py b/nova/compute/monitors/base.py index b0eced3b0d34..bbc5d87e093d 100644 --- a/nova/compute/monitors/base.py +++ b/nova/compute/monitors/base.py @@ -40,8 +40,9 @@ class MonitorBase(object): Get available metric names, which are represented by a set of keys that can be used to check conflicts and duplications + :returns: set containing one or more values from - nova.objects.fields.MonitorMetricType.ALL constants + :py:attr: nova.objects.fields.MonitorMetricType.ALL """ raise NotImplementedError('get_metric_names') diff --git a/nova/network/neutronv2/api.py b/nova/network/neutronv2/api.py index 822b1607560b..dbdfc9142b67 100644 --- a/nova/network/neutronv2/api.py +++ b/nova/network/neutronv2/api.py @@ -820,10 +820,12 @@ class API(base_api.NetworkAPI): :param context - Request context. :param port_id - The id of port to be queried. - :returns: A dict containing port data keyed by 'port'. - e.g. {'port': {'port_id': 'abcd', - 'fixed_ip_address': '1.2.3.4'}} + :returns: A dict containing port data keyed by 'port', e.g. + :: + + {'port': {'port_id': 'abcd', + 'fixed_ip_address': '1.2.3.4'}} """ return dict(port=self._show_port(context, port_id)) @@ -835,7 +837,7 @@ class API(base_api.NetworkAPI): :param neutron_client - A neutron client. :param fields - The condition fields to query port data. :returns: A dict of port data. - e.g. {'port_id': 'abcd', 'fixed_ip_address': '1.2.3.4'}} + e.g. {'port_id': 'abcd', 'fixed_ip_address': '1.2.3.4'} """ if not neutron_client: neutron_client = get_client(context) diff --git a/nova/objects/base.py b/nova/objects/base.py index 7b4d3d8d62f9..6d778e21344b 100644 --- a/nova/objects/base.py +++ b/nova/objects/base.py @@ -469,15 +469,16 @@ class NovaObject(object): def obj_reset_changes(self, fields=None, recursive=False): """Reset the list of fields that have been changed. + .. note:: + + - This is NOT "revert to previous values" + - Specifying fields on recursive resets will only be honored at the + top level. Everything below the top will reset all. + :param fields: List of fields to reset, or "all" if None. :param recursive: Call obj_reset_changes(recursive=True) on any sub-objects within the list of fields being reset. - - NOTE: This is NOT "revert to previous values" - NOTE: Specifying fields on recursive resets will only be - honored at the top level. Everything below the top - will reset all. """ if recursive: for field in self.obj_get_changes(): diff --git a/nova/objects/image_meta.py b/nova/objects/image_meta.py index e35f1388bde7..e85e76c88e86 100644 --- a/nova/objects/image_meta.py +++ b/nova/objects/image_meta.py @@ -97,7 +97,7 @@ class ImageMeta(base.NovaObject): :param instance: Instance object Creates a new object instance, initializing from the - system metadata "image_" properties associated with + system metadata "image_*" properties associated with instance :returns: an ImageMeta instance diff --git a/nova/safe_utils.py b/nova/safe_utils.py index 4f1558115980..e6a187a9f4a2 100644 --- a/nova/safe_utils.py +++ b/nova/safe_utils.py @@ -27,8 +27,8 @@ def getcallargs(function, *args, **kwargs): This method can only properly grab arguments which are passed in as keyword arguments, or given names by the method being called. This means - that an *arg in a method signature and any arguments captured by it will - be left out of the results. + that an ``*arg`` in a method signature and any arguments captured by it + will be left out of the results. """ keyed_args = {} argnames, varargs, keywords, defaults = inspect.getargspec(function) diff --git a/nova/tests/functional/wsgi/test_flavor_manage.py b/nova/tests/functional/wsgi/test_flavor_manage.py index 26a0b35dbcf6..11f85b852242 100644 --- a/nova/tests/functional/wsgi/test_flavor_manage.py +++ b/nova/tests/functional/wsgi/test_flavor_manage.py @@ -47,24 +47,26 @@ class FlavorManageFullstack(test.TestCase): POST /v2/flavors: - { - 'name': NAME, # string, required unique - 'id': ID, # string, required unique - 'ram': RAM, # in MB, required - 'vcpus': VCPUS, # int value, required - 'disk': DISK, # in GB, required - 'OS-FLV-EXT-DATA:ephemeral', # in GB, ephemeral disk size - 'is_public': IS_PUBLIC, # boolean - 'swap': SWAP, # in GB? - 'rxtx_factor': RXTX, # ??? - } + :: + + { + 'name': NAME, # string, required unique + 'id': ID, # string, required unique + 'ram': RAM, # in MB, required + 'vcpus': VCPUS, # int value, required + 'disk': DISK, # in GB, required + 'OS-FLV-EXT-DATA:ephemeral', # in GB, ephemeral disk size + 'is_public': IS_PUBLIC, # boolean + 'swap': SWAP, # in GB? + 'rxtx_factor': RXTX, # ??? + } Returns Flavor DELETE /v2/flavors/ID - Functional Test Scope:: + Functional Test Scope: This test starts the wsgi stack for the nova api services, uses an in memory database to ensure the path through the wsgi layer to diff --git a/nova/utils.py b/nova/utils.py index 6fc4a9be3e18..ee4afce3c58c 100644 --- a/nova/utils.py +++ b/nova/utils.py @@ -83,19 +83,6 @@ utils_opts = [ help='Explicitly specify the temporary working directory'), ] -""" This group is for very specific reasons. - -If you're: -- Working around an issue in a system tool (e.g. libvirt or qemu) where the fix - is in flight/discussed in that community. -- The tool can be/is fixed in some distributions and rather than patch the code - those distributions can trivially set a config option to get the "correct" - behavior. -This is a good place for your workaround. - -Please use with care! -Document the BugID that your workaround is paired with.""" - workarounds_opts = [ cfg.BoolOpt('disable_rootwrap', default=False, @@ -138,6 +125,23 @@ workarounds_opts = [ "the Nova database they will have to be synchronized " "manually. See https://bugs.launchpad.net/bugs/1444630"), ] +""" The workarounds_opts group is for very specific reasons. + +If you're: + + - Working around an issue in a system tool (e.g. libvirt or qemu) where the + fix is in flight/discussed in that community. + - The tool can be/is fixed in some distributions and rather than patch the + code those distributions can trivially set a config option to get the + "correct" behavior. + +Then this is a good place for your workaround. + +.. warning:: + + Please use with care! Document the BugID that your workaround is paired with. +""" + CONF = cfg.CONF CONF.register_opts(monkey_patch_opts) CONF.register_opts(utils_opts) diff --git a/nova/virt/driver.py b/nova/virt/driver.py index 3b86c0864cb2..2b18ebc86bfb 100644 --- a/nova/virt/driver.py +++ b/nova/virt/driver.py @@ -82,13 +82,13 @@ def get_block_device_info(instance, block_device_mapping): Virt drivers expect block device mapping to be presented in the format of a dict containing the following keys: - root_device_name: device name of the root disk - ephemerals: a (potentially empty) list of DriverEphemeralBlockDevice - instances - swap: An instance of DriverSwapBlockDevice or None - block_device_mapping: a (potentially empty) list of - DriverVolumeBlockDevice or any of it's more - specialized subclasses. + - root_device_name: device name of the root disk + - ephemerals: a (potentially empty) list of DriverEphemeralBlockDevice + instances + - swap: An instance of DriverSwapBlockDevice or None + - block_device_mapping: a (potentially empty) list of + DriverVolumeBlockDevice or any of it's more + specialized subclasses. """ from nova.virt import block_device as virt_block_device diff --git a/nova/virt/hyperv/vhdutilsv2.py b/nova/virt/hyperv/vhdutilsv2.py index da31b8922720..07f267d42a76 100644 --- a/nova/virt/hyperv/vhdutilsv2.py +++ b/nova/virt/hyperv/vhdutilsv2.py @@ -126,15 +126,12 @@ class VHDUtilsV2(vhdutils.VHDUtils): new_vhd_file_size): """Get internal size of a VHD according to new VHD file size. - .. math:: - VHDX Size = Header (1 MB) + Log + Metadata Region + BAT - + Payload Blocks + VHDX Size = Header (1MB) + Log + Metadata Region + BAT + Payload Blocks The chunk size is the maximum number of bytes described by a SB block. - .. math:: - Chunk size = 2^{23} * LogicalSectorSize + Chunk size = 2^{23} * LogicalSectorSize :param str vhd_path: VHD file path :param new_vhd_file_size: Size of the new VHD file. diff --git a/nova/virt/libvirt/driver.py b/nova/virt/libvirt/driver.py index 8bdd6eeafccd..6d65cd9b9905 100644 --- a/nova/virt/libvirt/driver.py +++ b/nova/virt/libvirt/driver.py @@ -4902,11 +4902,13 @@ class LibvirtDriver(driver.ComputeDriver): :param context: security context :param instance: nova.objects.instance.Instance object - :returns - :tempfile: A dict containing the tempfile info on the destination - host - :None: 1. If the instance path is not existing. - 2. If the image backend is shared block storage type. + :returns: + - tempfile: A dict containing the tempfile info on the destination + host + - None: + + 1. If the instance path is not existing. + 2. If the image backend is shared block storage type. """ if self.image_backend.backend().is_shared_block_storage(): return None diff --git a/nova/virt/libvirt/host.py b/nova/virt/libvirt/host.py index 2a4b0e8e242e..f417a06e117c 100644 --- a/nova/virt/libvirt/host.py +++ b/nova/virt/libvirt/host.py @@ -845,9 +845,10 @@ class Host(object): def create_secret(self, usage_type, usage_id, password=None): """Create a secret. - usage_type: one of 'iscsi', 'ceph', 'rbd' or 'volume' + :param usage_type: one of 'iscsi', 'ceph', 'rbd' or 'volume' 'rbd' will be converted to 'ceph'. - usage_id: name of resource in secret + :param usage_id: name of resource in secret + :param password: optional secret value to set """ secret_conf = vconfig.LibvirtConfigSecret() secret_conf.ephemeral = False diff --git a/nova/virt/opts.py b/nova/virt/opts.py index 4b2cbd4c4544..bea8a2a999b3 100644 --- a/nova/virt/opts.py +++ b/nova/virt/opts.py @@ -30,10 +30,10 @@ import nova.virt.ironic.driver import nova.virt.libvirt.driver import nova.virt.libvirt.imagebackend import nova.virt.libvirt.imagecache -import nova.virt.libvirt.lvm +import nova.virt.libvirt.storage.lvm import nova.virt.libvirt.utils import nova.virt.libvirt.vif -import nova.virt.libvirt.volume +import nova.virt.libvirt.volume.volume import nova.virt.netutils import nova.virt.vmwareapi.driver import nova.virt.vmwareapi.images @@ -81,10 +81,10 @@ def list_opts(): nova.virt.libvirt.driver.libvirt_opts, nova.virt.libvirt.imagebackend.__imagebackend_opts, nova.virt.libvirt.imagecache.imagecache_opts, - nova.virt.libvirt.lvm.lvm_opts, + nova.virt.libvirt.storage.lvm.lvm_opts, nova.virt.libvirt.utils.libvirt_opts, nova.virt.libvirt.vif.libvirt_vif_opts, - nova.virt.libvirt.volume.volume_opts, + nova.virt.libvirt.volume.volume.volume_opts, )), ('vmware', itertools.chain( diff --git a/setup.cfg b/setup.cfg index 1c83402c864a..58a27df52138 100644 --- a/setup.cfg +++ b/setup.cfg @@ -218,5 +218,14 @@ output_file = nova/locale/nova.pot universal = 1 [pbr] -autodoc_index_modules = 0 +# Have pbr generate the module indexes like sphinx autodoc +autodoc_index_modules = True + +# Exclude modules that won't build with autodoc (or that we don't want doc'ed); +# this requires updating the exclude_patterns variable in doc/source/conf.py +autodoc_exclude_modules = nova.wsgi.nova-* + nova.tests.* + +# Treat sphinx warnings as errors during the docs build; this helps us keep +# the documentation clean. warnerrors = true