Enable module reference

Also fixes sphinx warnings in existing docstrings.

Change-Id: Iccccd782ff8b80a3fd2764e7ef9cc3dde46e32ee

.gitignore

@@ -7,6 +7,7 @@ cover/
 covhtml/
 dist/
 doc/build
+doc/source/reference/modules/
 *.DS_Store
 *.pyc
 neutron_lib.egg-info/

doc/source/index.rst

@@ -45,4 +45,8 @@ Enjoy!
    install/index
    user/index
    contributor/index
+
+.. toctree::
+   :maxdepth: 1
+
    reference/index

doc/source/reference/index.rst

@@ -25,10 +25,9 @@ Module Reference
 
 .. toctree::
    :maxdepth: 1
+   :glob:
 
-.. todo::
+   modules/*
-
-   Add in all the big modules as automodule indexes.
 
 * :ref:`genindex`
 * :ref:`search`

neutron_lib/api/attributes.py

@@ -70,9 +70,9 @@ class AttributeInfo(object):
         """Create a new instance that wraps the given resource attributes.
 
         :param resource_attrs: The resource's attributes that can be any
-        of the following types: an instance of AttributeInfo, an API definition
+            of the following types: an instance of AttributeInfo, an API
-        that contains a RESOURCE_ATTRIBUTE_MAP attribute or a dict of
+            definition that contains a RESOURCE_ATTRIBUTE_MAP attribute or
-        attributes for the resource.
+            a dict of attributes for the resource.
         """
         if isinstance(resource_attrs, AttributeInfo):
             resource_attrs = resource_attrs.attributes

neutron_lib/api/converters.py

@@ -175,6 +175,7 @@ def convert_ip_to_canonical_format(value):
               - 'value' if 'value' is IPv4 address,
               - 'value' if 'value' is not an IP Address
               - canonical IPv6 address if 'value' is IPv6 address.
+
     """
     try:
         ip = netaddr.IPAddress(value)
@@ -191,7 +192,7 @@ def convert_cidr_to_canonical_format(value):
     :param value: The CIDR which needs to be checked.
     :returns: - 'value' if 'value' is CIDR with IPv4 address,
               - CIDR with canonical IPv6 address if 'value' is IPv6 CIDR.
-    :raises:  - InvalidInput if 'value' is None, not a valid CIDR or
+    :raises: InvalidInput if 'value' is None, not a valid CIDR or
         invalid IP Format.
     """
     error_message = _("%s is not in a CIDR format") % value

neutron_lib/api/validators/__init__.py

@@ -167,7 +167,8 @@ def validate_not_empty_string_or_none(data, max_len=None):
     :param data: The data to validate.
     :param max_len: An optional cap on the str length to validate.
     :returns: None if the data string is not None and is not an empty string,
-    otherwise a human readable message as to why the string data is invalid.
+        otherwise a human readable message as to why the string data is
+        invalid.
     """
     if data is not None:
         return validate_not_empty_string(data, max_len=max_len)
@@ -561,8 +562,8 @@ def validate_hostroutes(data, valid_values=None):
     """Validate a list of unique host route dicts.
 
     :param data: The data to validate. To be valid it must be a list like
-    structure of host route dicts, each containing 'destination' and 'nexthop'
+        structure of host route dicts, each containing 'destination' and
-    key values.
+        'nexthop' key values.
     :param valid_values: Not used!
     :returns: None if data is a valid list of unique host route dicts,
         otherwise a human readable message indicating why validation failed.
@@ -609,8 +610,8 @@ def validate_ip_or_subnet_or_none(data, valid_values=None):
     :param data: The data to validate.
     :param valid_values: Not used!
     :return: None if data is None or a valid IP address or a valid IP subnet,
-    otherwise a human readable message indicating why the data is neither an
+        otherwise a human readable message indicating why the data is neither
-    IP address nor IP subnet.
+        an IP address nor IP subnet.
     """
     msg_ip = validate_ip_address_or_none(data)
     msg_subnet = validate_subnet_or_none(data)
@@ -815,8 +816,8 @@ def validate_dict(data, key_specs=None):
     :param key_specs: The optional list of keys that must be contained in
         data.
     :returns: None if data is a dict and (optionally) contains only key_specs.
-    Otherwise a human readable message is returned indicating why data is not
+        Otherwise a human readable message is returned indicating why data is
-    valid.
+        not valid.
     """
     if not isinstance(data, dict):
         msg = _("'%s' is not a dictionary") % data
@@ -858,8 +859,8 @@ def validate_dict_or_none(data, key_specs=None):
     :param key_specs: The optional list of keys that must be contained in
         data.
     :returns: None if data is None or a dict  that (optionally) contains
-    all key_specs. Otherwise a human readable message is returned indicating
+        all key_specs. Otherwise a human readable message is returned
-    why data is not valid.
+        indicating why data is not valid.
     """
     if data is not None:
         return validate_dict(data, key_specs)
@@ -872,8 +873,8 @@ def validate_dict_or_empty(data, key_specs=None):
     :param key_specs: The optional list of keys that must be contained in
         data.
     :returns: None if data is {} or a dict (optionally) containing
-    only key_specs. Otherwise a human readable message is returned indicating
+        only key_specs. Otherwise a human readable message is returned
-    why data is not valid.
+        indicating why data is not valid.
     """
     if data != {}:
         return validate_dict(data, key_specs)
@@ -886,8 +887,8 @@ def validate_dict_or_nodata(data, key_specs=None):
     :param key_specs: The optional list of keys that must be contained in
         data.
     :returns: None if no data/empty dict or a dict and (optionally) contains
-    all key_specs. Otherwise a human readable message is returned indicating
+        all key_specs. Otherwise a human readable message is returned
-    why data is not valid.
+        indicating why data is not valid.
     """
     if data:
         return validate_dict(data, key_specs)
@@ -920,8 +921,8 @@ def validate_port_range_or_none(data, valid_values=None):
     :param data: The data to validate
     :param valid_values: Not used!
     :returns: None if data is an int between 0 and 65535, or two ints between 0
-    and 65535 with a colon between them, otherwise a human readable message as
+        and 65535 with a colon between them, otherwise a human readable message
-    to why data is invalid.
+        as to why data is invalid.
     """
     if data is None:
         return
@@ -953,8 +954,8 @@ def validate_subports(data, valid_values=None):
     :param data: The data to validate.
     :param valid_values: Not used!
     :returns: None if data is a list of subport dicts each with a unique valid
-    port_id, segmentation_id and segmentation_type. Otherwise a human readable
+        port_id, segmentation_id and segmentation_type. Otherwise a human
-    message is returned indicating why the data is invalid.
+        readable message is returned indicating why the data is invalid.
     """
     if not isinstance(data, list):
         msg = _("Invalid data format for subports: '%s' is not a list") % data

neutron_lib/callbacks/manager.py

@@ -116,9 +116,9 @@ class CallbacksManager(object):
         :param trigger: The trigger. A reference to the sender of the event.
         :param payload: The optional event object to send to subscribers. If
             passed this must be an instance of BaseEvent.
-        :raises Invalid, CallbackFailure: The Invalid exception is raised if
+        :raises neutron_lib.callbacks.exceptions.Invalid: if
-        the payload object is not an instance of BaseEvent. CallbackFailure
+            the payload object is not an instance of BaseEvent.
-        is raise if the underlying callback has errors.
+        :raises CallbackFailure: if the underlying callback has errors.
         """
         if payload:
             if not isinstance(payload, events.EventPayload):

neutron_lib/utils/runtime.py

@@ -34,7 +34,7 @@ def load_class_by_alias_or_classname(namespace, name):
     :param namespace: The namespace where the alias is defined.
     :param name: The alias or class name of the class to be loaded.
     :returns: Class if it can be loaded.
-    :raises ImportError if class cannot be loaded.
+    :raises ImportError: if class cannot be loaded.
     """
 
     if not name:

neutron_lib/worker.py

@@ -29,6 +29,9 @@ class BaseWorker(service.ServiceBase):
     do this only once instead of in every API worker, for instance, it would
     define a BaseWorker class and the plugin would have get_workers return
     an array of BaseWorker instances. For example:
+
+    .. code-block:: python
+
         class MyPlugin(...):
             def get_workers(self):
                 return [MyPluginWorker()]

setup.cfg

@@ -44,3 +44,13 @@ input_file = neutron_lib/locale/neutron_lib.pot
 keywords = _ gettext ngettext l_ lazy_gettext
 mapping_file = babel.cfg
 output_file = neutron_lib/locale/neutron_lib.pot
+
+[pbr]
+autodoc_tree_index_modules = True
+autodoc_tree_excludes =
+  setup.py
+  neutron_lib/tests
+  # In case neutron_lib.legacy has no actual content, this causes
+  # an error in sphinx autodoc, so let's exclude it.
+  neutron_lib/legacy
+api_doc_dir = reference/modules