openstack/nova
Code Issues Proposed changes

Set autodoc_index_modules=True so tox -e docs builds module docs again

Browse Source 
Commit bd7e62f796 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 bd7e62f796.
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
This commit is contained in:
Matt Riedemann 2015-07-06 15:18:59 -07:00
parent a74f07a923
commit 8b24bf766d
16 changed files with 99 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
doc/source/conf.py
View File

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

2
doc/source/development.environment.rst
View File

@ -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.

10
doc/source/index.rst
View File

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

3
nova/compute/monitors/base.py
View File

@ -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')

10
nova/network/neutronv2/api.py
View File

@ -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)

11
nova/objects/base.py
View File

@ -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():

2
nova/objects/image_meta.py
View File

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

4
nova/safe_utils.py
View File

@ -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)

26
nova/tests/functional/wsgi/test_flavor_manage.py
View File

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

30
nova/utils.py
View File

@ -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)

14
nova/virt/driver.py
View File

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

7
nova/virt/hyperv/vhdutilsv2.py
View File

@ -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.

12
nova/virt/libvirt/driver.py
View File

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

5
nova/virt/libvirt/host.py
View File

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

8
nova/virt/opts.py
View File

@ -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(

11
setup.cfg
View File

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