Update Octavia docs for documentation migration

This patch updates the Octavia documentation in support of the
OpenStack documentation migration[1].

[1] https://specs.openstack.org/openstack/docs-specs/specs \
    /pike/os-manuals-migration.html

Change-Id: I97fd038b8050bfe776c3fca8336d9090f8236362
Depends-On: Ia750cb049c0f53a234ea70ce1f2bbbb7a2aa9454

.gitignore

@@ -7,7 +7,9 @@ cover/
 covhtml/
 dist/
 doc/build
-doc/source/devref/flow_diagrams/
+doc/source/configuration/_static/octavia.policy.yaml.sample
+doc/source/contributor/devref/flow_diagrams/
+doc/source/contributor/modules
 .idea/*
 *.DS_Store
 *.pyc

api-ref/source/index.rst

@@ -13,7 +13,7 @@ Current API version
 
 Supported API version
 
-    `Octavia API v1 <https://docs.openstack.org/developer/octavia/api/octaviaapi.html>`_
+    :doc:`v1/octaviaapi`
 
 Deprecated API version
 
@@ -23,6 +23,7 @@ Deprecated API version
    :hidden:
 
    v2/index
+   v1/octaviaapi
 
 The API status reflects the state of the endpoint on the service.
 

doc-requirements.txt

@@ -2,7 +2,6 @@ actdiag
 blockdiag
 docutils>=0.11
 nwdiag
-oslosphinx
 seqdiag
 sphinx>=1.6.2
 sphinxcontrib-actdiag

doc/source/admin/guides/operator-maintenance.rst

@@ -17,9 +17,9 @@
 Operator Maintenance  Guide
 ======================================
 This document is intended for operators. For a developer guide see the
-:doc:`dev-quick-start` in this documentation repository. For an end-user
+:doc:`../../contributor/guides/dev-quick-start` in this documentation
-guide, please see the :doc:`basic-cookbook` in this documentation
+repository. For an end-user guide, please see the
-repository.
+:doc:`../../user/guides/basic-cookbook` in this documentation repository.
 
 Monitoring
 ==========
@@ -40,7 +40,8 @@ monitoring of the other services showed problems as well, so depending on
 your overall monitoring strategy this might be optional.
 
 If additional monitoring is necessary, review the corresponding calls on
-the amphora agent REST interface (see :doc:`../api/haproxy-amphora-api`)
+the amphora agent REST interface (see
+:doc:`../../contributor/api/haproxy-amphora-api`)
 
 Monitoring Pool Members
 -----------------------
@@ -286,7 +287,7 @@ Rotating Amphora Certificates
 -----------------------------
 
 For the server part Octavia will either act as a certificate authority itself,
-or use :doc:`../main/Anchor` to issue amphora certificates to be used
+or use :doc:`../Anchor` to issue amphora certificates to be used
 by each amphora. Octavia will also monitor those certificates and refresh them
 before they expire.
 
@@ -310,7 +311,7 @@ There are three ways to initiate a rotation manually:
   issued amphora certificates by switching off validation of the old amphora
   certificate. This requires a client certificate which can be validated by the
   client CA file on the amphora. Refer to
-  :doc:`../api/haproxy-amphora-api` for more details.
+  :doc:`../../contributor/api/haproxy-amphora-api` for more details.
 
 * If the client certificate on the control plane changed in a way that it can't
   be validated by the client certificate authority certificate on the amphora,
@@ -336,7 +337,7 @@ find them.
 to the new certs in the configuration file and restart all Octavia services
 (except octavia-api).
 
-# Review :ref:`_rotate-amphora-certs` above to determine if and how the
+# Review :ref:`rotate-amphora-certs` above to determine if and how the
 amphora certificates needs to be rotated.
 
 Rotating Client Certificates

doc/source/admin/index.rst

@@ -0,0 +1,41 @@
+======================
+Octavia Administration
+======================
+
+
+Getting Started
+---------------
+
+.. toctree::
+   :maxdepth: 1
+
+   ../reference/introduction.rst
+   ../reference/glossary.rst
+
+APIs
+----
+
+.. toctree::
+   :maxdepth: 1
+
+   Octavia API Reference <https://developer.openstack.org/api-ref/load-balancer/>
+   ../contributor/api/haproxy-amphora-api.rst
+
+
+Operator Reference
+------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   ../contributor/guides/dev-quick-start.rst
+   guides/operator-maintenance.rst
+   ../configuration/configref.rst
+   ../configuration/policy.rst
+   Anchor.rst
+   apache-httpd.rst
+
+Indices and Search
+------------------
+
+* :ref:`search`

doc/source/conf.py

@@ -18,12 +18,13 @@ from tools import create_flow_docs
 
 # Generate our flow diagrams
 create_flow_docs.generate(
-    'tools/flow-list.txt', 'doc/source/devref/flow_diagrams')
+    'tools/flow-list.txt', 'doc/source/contributor/devref/flow_diagrams')
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('../../octavia'))
 
 # -- General configuration -----------------------------------------------------
 
@@ -40,7 +41,7 @@ extensions = ['sphinx.ext.autodoc',
               'sphinxcontrib.seqdiag',
               'sphinxcontrib.nwdiag',
               'sphinx.ext.graphviz',
-              'oslosphinx',
+              'openstackdocstheme',
               'oslo_config.sphinxext',
               'oslo_policy.sphinxpolicygen'
              ]
@@ -75,7 +76,9 @@ copyright = u'2014, OpenStack Octavia Team'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build', 'specs/skeleton.rst', 'specs/template.rst']
+exclude_patterns = ['_build',
+                    'contributor/specs/skeleton.rst',
+                    'contributor/specs/template.rst']
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 #default_role = None
@@ -104,7 +107,7 @@ man_pages = []
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'nature'
+html_theme = 'openstackdocs'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -134,9 +137,7 @@ html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
-git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local",
+html_last_updated_fmt = '%Y-%m-%d %H:%M'
-           "-n1"]
-html_last_updated_fmt = subprocess.check_output(git_cmd).decode('utf-8')
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
@@ -150,10 +151,10 @@ html_last_updated_fmt = subprocess.check_output(git_cmd).decode('utf-8')
 #html_additional_pages = {}
 
 # If false, no module index is generated.
-html_domain_indices = False
+html_domain_indices = True
 
 # If false, no index is generated.
-html_use_index = False
+html_use_index = True
 
 # If true, the index is split into individual pages for each letter.
 #html_split_index = False
@@ -284,4 +285,12 @@ epub_copyright = u'2014, OpenStack Octavia Team'
 
 # RBAC sample policy file generation
 policy_generator_config_file = '../../etc/policy/octavia-policy-generator.conf'
-sample_policy_basename = '_static/octavia'
+sample_policy_basename = 'configuration/_static/octavia'
+
+# openstackdocstheme options
+html_theme_options = {
+    "display_toc": False
+}
+repository_name = 'openstack/octavia'
+bug_project = 'octavia'
+bug_tag = 'docs'

doc/source/configuration/index.rst

@@ -0,0 +1,9 @@
+=====================
+Octavia Configuration
+=====================
+
+.. toctree::
+   :maxdepth: 1
+
+   configref
+   policy

doc/source/configuration/policy.rst

@@ -76,4 +76,4 @@ in effective policy::
 Default Octavia Policies
 ------------------------
 
-.. literalinclude:: ../_static/octavia.policy.yaml.sample
+.. literalinclude:: _static/octavia.policy.yaml.sample

doc/source/contributor/design/version0.5/v0.5-component-design.dot

@@ -63,7 +63,12 @@ digraph G {
           </tr>
           <tr>
             <td sides="l"></td>
-            <td sides="ltb"></td>
+            <!-- TODO(johnsom) Change back to sides="ltb" when dot is fixed -->
+            <!-- This is commented out as it causes the current version -->
+            <!-- of dot to crash on Ubuntu.  <graphviz 2.38.0-12ubuntu2.1> -->
+            <!-- Which causes gate failures. -->
+            <!-- <td sides="ltb"></td> -->
+            <td sides="lb"></td>
             <td sides="tb" port="driver"><font point-size="10">Driver</font></td>
             <td sides="trb"></td>
             <td sides="r"></td>

doc/source/contributor/guides/dev-quick-start.rst

@@ -301,7 +301,7 @@ Configuring Octavia
 ___________________
 Going into all of the specifics of how Octavia can be configured is actually
 beyond the scope of this document. For full documentation of this, please see
-the configuration reference: :doc:`../main/configref`
+the configuration reference: :doc:`../../configuration/configref`
 
 A configuration template can be found in ``etc/octavia.conf`` in this
 repository.

doc/source/contributor/index.rst

@@ -0,0 +1,88 @@
+===================
+Octavia Contributor
+===================
+
+Contributor Guidelines
+----------------------
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   CONSTITUTION.rst
+   HACKING.rst
+
+Contributor Reference
+---------------------
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   guides/*
+   devref/*
+
+
+Internal APIs
+-------------
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   api/*
+
+Design Documentation
+--------------------
+
+Version 0.5 (liberty)
+`````````````````````
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   design/version0.5/*
+
+Project Specifications
+----------------------
+
+Version 0.5 (liberty)
+`````````````````````
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   specs/version0.5/*
+
+Version 0.8 (mitaka)
+````````````````````
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   specs/version0.8/*
+
+Version 0.9 (newton)
+````````````````````
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   specs/version0.9/*
+
+Version 1.0 (pike)
+``````````````````
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   specs/version1.0/*
+
+Indices and Search
+------------------
+
+.. toctree::
+   :hidden:
+
+   modules/autoindex
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

doc/source/contributor/specs

@@ -0,0 +1 @@
+../../../specs

doc/source/index.rst

@@ -1,119 +1,28 @@
-.. octavia-specs documentation master file
+.. octavia documentation master file
 
 =====================
 Octavia Documentation
 =====================
 
-Getting started
+Welcome to the OpenStack Octavia project documentation. Octavia brings
----------------
+network load balancing to OpenStack.
+
+See :doc:`reference/introduction` for an overview of Octavia.
+
+To align with the overall OpenStack documentation, the Octavia documentation
+is grouped into the following topic areas.
 
 .. toctree::
    :maxdepth: 1
 
-   main/introduction.rst
+   admin/index.rst
-   main/glossary.rst
-
-For users
----------
-
-.. toctree::
-   :maxdepth: 1
-
-   guides/basic-cookbook.rst
-   guides/l7.rst
-   guides/l7-cookbook.rst
-
-For developers
---------------
-
-.. toctree::
-   :maxdepth: 1
-
-   guides/dev-quick-start.rst
-   main/CONSTITUTION.rst
-   main/HACKING.rst
-   devref/flows.rst
-   main/gmr.rst
-
-For operators
--------------
-
-.. toctree::
-   :maxdepth: 1
-
-   guides/dev-quick-start.rst
-   guides/operator-maintenance.rst
-   main/configref.rst
-   main/policy.rst
-   main/Anchor.rst
-   devref/apache-httpd.rst
-
-====
-APIs
-====
-
-.. toctree::
-   :glob:
-   :maxdepth: 1
-
    Octavia API Reference <https://developer.openstack.org/api-ref/load-balancer/>
-   api/haproxy-amphora-api.rst
+   configuration/index.rst
+   contributor/index.rst
+   install/index.rst
+   reference/index.rst
+   user/index.rst
 
-====================
-Design Documentation
-====================
 
-Version 0.5 (liberty)
----------------------
 
-.. toctree::
+:ref:`search`
-   :glob:
-   :maxdepth: 1
-
-   design/version0.5/*
-
-======================
-Project Specifications
-======================
-
-Version 0.5 (liberty)
----------------------
-
-.. toctree::
-   :glob:
-   :maxdepth: 1
-
-   specs/version0.5/*
-
-Version 0.8 (mitaka)
---------------------
-
-.. toctree::
-   :glob:
-   :maxdepth: 1
-
-   specs/version0.8/*
-
-Version 0.9 (newton)
---------------------
-
-.. toctree::
-   :glob:
-   :maxdepth: 1
-
-   specs/version0.9/*
-
-Version 1.0
------------
-
-.. toctree::
-   :glob:
-   :maxdepth: 1
-
-   specs/version1/*
-
-==================
-Indices and tables
-==================
-
-* :ref:`search`

doc/source/install/index.rst

@@ -0,0 +1,8 @@
+====================
+Octavia Installation
+====================
+
+.. toctree::
+    :maxdepth: 1
+
+    Installation overview guide <../contributor/guides/dev-quick-start>

doc/source/reference/index.rst

@@ -0,0 +1,16 @@
+=================
+Octavia Reference
+=================
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   *
+
+Indices and Search
+------------------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

doc/source/reference/introduction.rst

@@ -148,5 +148,5 @@ Octavia version 0.9 consists of the following major components:
   service is deployed by the tenant.
 
 For a more complete description of Octavia's components, please see the
-:doc:`../design/version0.5/component-design` document within this documentation
+:doc:`../contributor/design/version0.5/component-design` document within this
-repository.
+documentation repository.

doc/source/specs

@@ -1 +0,0 @@
-../../specs

doc/source/user/guides/basic-cookbook.rst

@@ -32,9 +32,9 @@ TLS certificates from a trusted provider, and so on. A description of the
 starting conditions is given in each example below.
 
 Please also note that this guide assumes you are familiar with the specific
-load balancer terminology defined in the :doc:`../main/glossary`. For a
+load balancer terminology defined in the :doc:`../../reference/glossary`. For a
 description of load balancing itself and the Octavia project, please see:
-:doc:`../main/introduction`.
+:doc:`../../reference/introduction`.
 
 
 Examples
@@ -537,7 +537,7 @@ them out of the pool. Since effective health monitors depend as much on
 back-end application server configuration as proper load balancer
 configuration, some additional discussion of best practices is warranted here.
 
-See also: :doc:`../api/octaviaapi`
+See also: `Octavia API Reference <https://developer.openstack.org/api-ref/load-balancer/>`_
 
 
 Heath monitor options

doc/source/user/guides/l7-cookbook.rst

@@ -36,8 +36,8 @@ Examples
 
 .. _redirect-http-to-https:
 
-Redirect http://www.example.com/ to https://www.example.com/
+Redirect *http://www.example.com/* to *https://www.example.com/*
-------------------------------------------------------------
+----------------------------------------------------------------
 **Scenario description**:
 
 * Load balancer *lb1* has been set up with ``TERMINATED_HTTPS`` listener
@@ -121,8 +121,8 @@ Send requests starting with /js or /images to *static_pool*
     neutron lbaas-l7rule-create --type PATH --compare-type REGEX --value '^/(js|images)' policy1
 
 
-Send requests for http://www2.example.com/ to *pool2*
+Send requests for *http://www2.example.com/* to *pool2*
------------------------------------------------------
+-------------------------------------------------------
 **Scenario description**:
 
 * Listener *listener1* on load balancer *lb1* is set up to send all requests to

doc/source/user/guides/l7.rst

@@ -70,7 +70,7 @@ It consists of a rule type, a comparison type, a value, and an optional key
 that gets used depending on the rule type. An L7 rule must always be associated
 with an L7 policy.
 
-See also: :doc:`../api/octaviaapi`
+See also: `Octavia API Reference <https://developer.openstack.org/api-ref/load-balancer/>`_
 
 Rule types
 __________
@@ -115,7 +115,7 @@ may also have an association to a back-end pool. Policies describe actions that
 should be taken by the load balancing software if all of the rules in the
 policy return true.
 
-See also: :doc:`../api/octaviaapi`
+See also: `Octavia API Reference <https://developer.openstack.org/api-ref/load-balancer/>`_
 
 Policy Logic
 ____________
@@ -180,6 +180,6 @@ For a cookbook of common L7 usage examples, please see the :doc:`l7-cookbook`
 
 Useful links
 ============
-* :doc:`../api/octaviaapi`
+* `Octavia API Reference <https://developer.openstack.org/api-ref/load-balancer/>`_
 * https://github.com/openstack/neutron-specs/blob/master/specs/mitaka/lbaas-l7-rules.rst
 * http://cbonte.github.io/haproxy-dconv/1.6/configuration.html#7

doc/source/user/index.rst

@@ -0,0 +1,15 @@
+============
+Octavia User
+============
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   guides/*
+
+Indices and Search
+------------------
+
+* :ref:`genindex`
+* :ref:`search`

octavia/amphorae/backends/utils/haproxy_query.py

@@ -76,20 +76,17 @@ class HAProxyQuery(object):
     def show_stat(self, proxy_iid=-1, object_type=-1, server_id=-1):
         """Get and parse output from 'show status' command.
 
-        :param proxy_iid:
+        :param proxy_iid: Proxy ID (column 27 in CSV output). -1 for all.
-          Proxy ID (column 27 in CSV output). -1 for all.
+        :param object_type: Select the type of dumpable object. Values can
-
+                            be ORed.
-        :param object_type:
-          Select the type of dumpable object. Values can be ORed.
                             -1 - everything
                             1 - frontends
                             2 - backends
                             4 - servers
+        :param server_id: Server ID (column 28 in CSV output?), or -1
+                          for everything.
+        :returns: stats (split into an array by newline)
 
-        :param server_id:
-          Server ID (column 28 in CSV output?), or -1 for everything.
-
-        :returns: stats (split into an array by \n)
         """
 
         results = self._query(
@@ -108,9 +105,7 @@ class HAProxyQuery(object):
                   {<pool-name>: {
                   'uuid': <uuid>,
                   'status': 'UP'|'DOWN',
-          'members': [
+                  'members': [<name>: 'UP'|'DOWN'] }}
-            <name>: 'UP'|'DOWN'
-          ]
         """
 
         results = self.show_stat(object_type=6)  # servers + pool

octavia/amphorae/drivers/driver_base.py

@@ -60,7 +60,7 @@ class AmphoraLoadBalancerDriver(object):
         :param listener: listener object,
                          need to use its protocol_port property
         :type listener: object
-        :param vip : vip object, need to use its ip_address property
+        :param vip: vip object, need to use its ip_address property
         :type vip: object
         :returns: return a value list (listener, vip, status flag--enable)
 

octavia/amphorae/drivers/health/heartbeat_udp.py

@@ -81,7 +81,10 @@ class UDPStatusGetter(object):
                  can be seen below. Note that listener_1 has no pools
                  and listener_4 has no members.
 
-        {"listeners": {
+        Example::
+
+            {
+              "listeners": {
                 "listener_uuid_1": {
                   "pools": {},
                   "status": "OPEN",
@@ -94,8 +97,7 @@ class UDPStatusGetter(object):
                 "listener_uuid_2": {
                   "pools": {
                     "pool_uuid_1": {
-                    "members": [
+                      "members": [{
-                        {
                           "member_uuid_1": "DOWN"
                         },
                         {
@@ -120,8 +122,7 @@ class UDPStatusGetter(object):
                 "listener_uuid_3": {
                   "pools": {
                     "pool_uuid_2": {
-                    "members": [
+                      "members": [{
-                        {
                           "member_uuid_5": "DOWN"
                         },
                         {
@@ -159,7 +160,7 @@ class UDPStatusGetter(object):
               },
               "id": "amphora_uuid",
               "seq": 1033
-}
+            }
 
         """
         (data, srcaddr) = self.sock.recvfrom(UDP_MAX_SIZE)

octavia/common/decorators.py

@@ -20,8 +20,9 @@ def rename_kwargs(**renamed_kwargs):
     """Renames a class's variables and maintains backwards compatibility.
 
     :param renamed_kwargs: mapping of old kwargs to new kwargs.  For example,
-    to say a class has renamed variable foo to bar the decorator would
+                           to say a class has renamed variable foo to bar the
-    be used like: rename_kwargs(foo='bar')
+                           decorator would be used like:
+                           rename_kwargs(foo='bar')
 
     """
 

octavia/common/tls_utils/cert_parser.py

@@ -243,9 +243,9 @@ def get_host_names(certificate):
     :param certificate: A PEM encoded certificate
     :returns: A dictionary containing the following keys:
               ['cn', 'dns_names']
-    where 'cn' is the CN from the SubjectName of the certificate, and
+              where 'cn' is the CN from the SubjectName of the
-    'dns_names' is a list of dNSNames (possibly empty) from
+              certificate, and 'dns_names' is a list of dNSNames
-    the SubjectAltNames of the certificate.
+              (possibly empty) from the SubjectAltNames of the certificate.
     """
     try:
         cert = x509.load_pem_x509_certificate(certificate,

octavia/compute/compute_base.py

@@ -35,13 +35,15 @@ class ComputeBase(object):
         :param sec_groups: Optionally specify list of security groups
         :param network_ids: A list of network IDs to attach to the amphora
         :param config_drive_files: An optional dict of files to overwrite on
-        the server upon boot. Keys are file names (i.e. /etc/passwd)
+                                   the server upon boot. Keys are file names
-        and values are the file contents (either as a string or as
+                                   (i.e. /etc/passwd) and values are the
-        a file-like object). A maximum of five entries is allowed,
+                                   file contents (either as a string or as
-        and each file must be 10k or less.
+                                   a file-like object). A maximum of five
+                                   entries is allowed, and each file must be
+                                   10k or less.
         :param user_data: Optional user data to pass to be exposed by the
-        metadata server this can be a file type object as well or
+                          metadata server this can be a file type object as
-        a string
+                          well or a string
         :param server_group_id: Optional server group id(uuid) which is used
                                 for anti_affinity feature
 

octavia/compute/drivers/nova_driver.py

@@ -104,18 +104,21 @@ class VirtualMachineManager(compute_base.ComputeBase):
         :param network_ids: Network IDs to include on virtual machine
         :param port_ids: Port IDs to include on virtual machine
         :param config_drive_files:  An optional dict of files to overwrite on
-        the server upon boot. Keys are file names (i.e. /etc/passwd)
+                                    the server upon boot. Keys are file names
-        and values are the file contents (either as a string or as
+                                    (i.e. /etc/passwd) and values are the file
-        a file-like object). A maximum of five entries is allowed,
+                                    contents (either as a string or as a
-        and each file must be 10k or less.
+                                    file-like object). A maximum of five
+                                    entries is allowed, and each file must be
+                                    10k or less.
         :param user_data: Optional user data to pass to be exposed by the
-        metadata server this can be a file type object as well or
+                          metadata server this can be a file type object as
-        a string
+                          well or a string
         :param server_group_id: Optional server group id(uuid) which is used
                                 for anti_affinity feature
 
         :raises ComputeBuildException: if nova failed to build virtual machine
         :returns: UUID of amphora
+
         '''
 
         try:

octavia/controller/healthmanager/update_db.py

@@ -67,14 +67,15 @@ class UpdateHealthDb(object):
         :type map: string
         :returns: null
 
-        The input health data structure is shown as below:
+        The input health data structure is shown as below::
 
             health = {
                 "id": self.FAKE_UUID_1,
                 "listeners": {
                     "listener-id-1": {"status": constants.OPEN, "pools": {
                         "pool-id-1": {"status": constants.UP,
-                                  "members": {"member-id-1": constants.ONLINE}
+                                      "members": {
+                                          "member-id-1": constants.ONLINE}
                                       }
                     }
                     }
@@ -228,6 +229,8 @@ class UpdateStatsDb(stats.StatsMixin):
         :type map: string
         :returns: null
 
+        Example::
+
             health = {
                 "id": self.FAKE_UUID_1,
                 "listeners": {

octavia/controller/worker/flows/listener_flows.py

@@ -88,6 +88,7 @@ class ListenerFlows(object):
         """Create a flow to delete a listener and l7policies internally
 
            (will skip deletion on the amp and marking LB active)
+
         :returns: The flow for deleting a listener
         """
         delete_listener_flow = linear_flow.Flow(constants.DELETE_LISTENER_FLOW)

octavia/controller/worker/tasks/network_tasks.py

@@ -90,6 +90,7 @@ class CalculateDelta(BaseNetworkTask):
         """Compute which NICs need to be plugged
 
         for the amphora to become operational.
+
         :param loadbalancer: the loadbalancer to calculate deltas for all
                              amphorae
         :returns: dict of octavia.network.data_models.Delta keyed off amphora

octavia/db/repositories.py

@@ -671,8 +671,9 @@ class LoadBalancerRepository(BaseRepository):
         :param session: A Sql Alchemy database session.
         :param lb_id: id of an load balancer object
         :param exp_age: A standard datetime delta which is used to see for how
-        long can a load balancer live without updates before it is considered
+                        long can a load balancer live without updates before
-        expired (default: CONF.house_keeping.load_balancer_expiry_age)
+                        it is considered expired (default:
+                        CONF.house_keeping.load_balancer_expiry_age)
         :returns: boolean
         """
         if not exp_age:
@@ -1032,8 +1033,9 @@ class AmphoraHealthRepository(BaseRepository):
         :param session: A Sql Alchemy database session.
         :param amphora_id: id of an amphora object
         :param exp_age: A standard datetime delta which is used to see for how
-        long can an amphora live without updates before it is considered
+                        long can an amphora live without updates before it is
-        expired (default: CONF.house_keeping.amphora_expiry_age)
+                        considered expired (default:
+                        CONF.house_keeping.amphora_expiry_age)
         :returns: boolean
         """
         if not exp_age:

octavia/hacking/checks.py

@@ -169,8 +169,8 @@ def no_translate_logs(logical_line, filename):
     :param logical_line: The logical line to check.
     :param filename: The file name where the logical line exists.
     :returns: None if the logical line passes the check, otherwise a tuple
-    is yielded that contains the offending index in logical line and a
+              is yielded that contains the offending index in logical line
-    message describe the check validation failure.
+              and a message describe the check validation failure.
     """
     if _translation_checks_not_enforced(filename):
         return
@@ -187,8 +187,8 @@ def check_raised_localized_exceptions(logical_line, filename):
     :param logical_line: The logical line to check.
     :param filename: The file name where the logical line exists.
     :returns: None if the logical line passes the check, otherwise a tuple
-    is yielded that contains the offending index in logical line and a
+              is yielded that contains the offending index in logical line
-    message describe the check validation failure.
+              and a message describe the check validation failure.
     """
     if _translation_checks_not_enforced(filename):
         return
@@ -208,8 +208,8 @@ def check_no_basestring(logical_line):
 
     :param logical_line: The logical line to check.
     :returns: None if the logical line passes the check, otherwise a tuple
-    is yielded that contains the offending index in logical line and a
+              is yielded that contains the offending index in logical line
-    message describe the check validation failure.
+              and a message describe the check validation failure.
     """
     if re.search(r"\bbasestring\b", logical_line):
         msg = ("O343: basestring is not Python3-compatible, use "
@@ -222,8 +222,8 @@ def check_python3_no_iteritems(logical_line):
 
     :param logical_line: The logical line to check.
     :returns: None if the logical line passes the check, otherwise a tuple
-    is yielded that contains the offending index in logical line and a
+              is yielded that contains the offending index in logical line
-    message describe the check validation failure.
+              and a message describe the check validation failure.
     """
     if re.search(r".*\.iteritems\(\)", logical_line):
         msg = ("O344: Use dict.items() instead of dict.iteritems() to be "
@@ -239,8 +239,8 @@ def check_no_eventlet_imports(logical_line):
 
     :param logical_line: The logical line to check.
     :returns: None if the logical line passes the check, otherwise a tuple
-    is yielded that contains the offending index in logical line and a
+              is yielded that contains the offending index in logical line
-    message describe the check validation failure.
+              and a message describe the check validation failure.
     """
     if re.match(r'(import|from)\s+[(]?eventlet', logical_line):
         msg = 'O345 Usage of Python eventlet module not allowed'
@@ -253,8 +253,8 @@ def check_line_continuation_no_backslash(logical_line, tokens):
     :param logical_line: The logical line to check. Not actually used.
     :param tokens: List of tokens to check.
     :returns: None if the tokens don't contain any issues, otherwise a tuple
-    is yielded that contains the offending index in the logical line and a
+              is yielded that contains the offending index in the logical
-    message describe the check validation failure.
+              line and a message describe the check validation failure.
     """
     backslash = None
     for token_type, text, start, end, orig_line in tokens:

octavia/network/base.py

@@ -293,8 +293,7 @@ class AbstractNetworkDriver(object):
         means the driver is responsible for providing data that is appropriate
         for the amphora network configurations.
 
-        Example return:
+        Example return: {<amphora.id>: <AmphoraNetworkConfig>}
-        {<amphora.id>: <AmphoraNetworkConfig>}
 
         :param load_balancer: The load_balancer configuration
         :return: dict of octavia.network.data_models.AmphoraNetworkConfig

octavia/opts.py

@@ -25,6 +25,7 @@ def list_opts():
     return [
         ('DEFAULT',
          itertools.chain(octavia.common.config.core_opts)),
+        ('api_settings', octavia.common.config.api_opts),
         ('amphora_agent', octavia.common.config.amphora_agent_opts),
         ('networking', octavia.common.config.networking_opts),
         ('oslo_messaging', octavia.common.config.oslo_messaging_opts),
@@ -35,9 +36,11 @@ def list_opts():
         ('certificates', octavia.common.config.certificate_opts),
         ('house_keeping', octavia.common.config.house_keeping_opts),
         ('keepalived_vrrp', octavia.common.config.keepalived_vrrp_opts),
+        ('anchor', octavia.common.config.anchor_opts),
         ('nova', octavia.common.config.nova_opts),
         ('neutron', octavia.common.config.neutron_opts),
         ('glance', octavia.common.config.glance_opts),
+        ('quotas', octavia.common.config.quota_opts),
         add_auth_opts(),
     ]
 

releasenotes/source/conf.py

@@ -39,7 +39,7 @@ from octavia import version
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'oslosphinx',
+    'openstackdocstheme',
     'reno.sphinxext',
 ]
 
@@ -152,6 +152,7 @@ html_static_path = ['_static']
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 # html_last_updated_fmt = '%b %d, %Y'
+html_last_updated_fmt = '%Y-%m-%d %H:%M'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.

setup.cfg

@@ -41,9 +41,19 @@ data_files =
 all_files = 1
 build-dir = doc/build
 source-dir = doc/source
+warning-is-error = 1
 
 [pbr]
-warnerrors = True
+autodoc_tree_index_modules = False
+autodoc_tree_excludes =
+    setup.py
+    octavia/tests/
+    octavia/db/migration/
+autodoc_index_modules = True
+autodoc_exclude_modules =
+    octavia.tests.*
+    octavia.db.migration.*
+api_doc_dir = contributor/modules
 
 [wheel]
 universal = 1

specs/version0.9/active-active-distributor.rst

@@ -828,10 +828,10 @@ Documentation Impact
 References
 ==========
 
-.. [1] https://blueprints.launchpad.net/octavia/+spec/base-image
+https://blueprints.launchpad.net/octavia/+spec/base-image
-.. [2] https://blueprints.launchpad.net/octavia/+spec/controller-worker
+https://blueprints.launchpad.net/octavia/+spec/controller-worker
-.. [3] https://blueprints.launchpad.net/octavia/+spec/amphora-driver-interface
+https://blueprints.launchpad.net/octavia/+spec/amphora-driver-interface
-.. [4] https://blueprints.launchpad.net/octavia/+spec/controller
+https://blueprints.launchpad.net/octavia/+spec/controller
-.. [5] https://blueprints.launchpad.net/octavia/+spec/operator-api
+https://blueprints.launchpad.net/octavia/+spec/operator-api
-.. [6] :doc:`../../api/haproxy-amphora-api`
+:doc:`../../api/haproxy-amphora-api`
-.. [7] https://blueprints.launchpad.net/octavia/+spec/active-active-topology
+https://blueprints.launchpad.net/octavia/+spec/active-active-topology

specs/version0.9/active-active-topology.rst

@@ -626,10 +626,10 @@ Octavia with ACTIVE-ACTIVE topology.
 References
 ==========
 
-.. [1] https://blueprints.launchpad.net/octavia/+spec/base-image
+https://blueprints.launchpad.net/octavia/+spec/base-image
-.. [2] https://blueprints.launchpad.net/octavia/+spec/controller-worker
+https://blueprints.launchpad.net/octavia/+spec/controller-worker
-.. [3] https://blueprints.launchpad.net/octavia/+spec/amphora-driver-interface
+https://blueprints.launchpad.net/octavia/+spec/amphora-driver-interface
-.. [4] https://blueprints.launchpad.net/octavia/+spec/controller
+https://blueprints.launchpad.net/octavia/+spec/controller
-.. [5] https://blueprints.launchpad.net/octavia/+spec/operator-api
+https://blueprints.launchpad.net/octavia/+spec/operator-api
-.. [6] :doc:`../../api/haproxy-amphora-api`
+:doc:`../../api/haproxy-amphora-api`
-.. [7] https://blueprints.launchpad.net/octavia/+spec/active-active-topology
+https://blueprints.launchpad.net/octavia/+spec/active-active-topology

tools/create_flow_docs.py

@@ -98,7 +98,7 @@ def generate(flow_list, output_directory):
             current_doc_file.write('.. image:: ' + doc_tuple[0] +
                                    '-' + doc_tuple[1] + '.svg\n')
             current_doc_file.write('    :width: 660px\n')
-            current_doc_file.write('    :target: ../../_images/' +
+            current_doc_file.write('    :target: ../../../_images/' +
                                    doc_tuple[0] +
                                    '-' + doc_tuple[1] + '.svg\n')
 
@@ -129,7 +129,7 @@ def generate(flow_list, output_directory):
             current_doc_file.write('.. image:: ' + doc_tuple[0] +
                                    '-' + doc_tuple[1] + '.svg\n')
             current_doc_file.write('    :width: 660px\n')
-            current_doc_file.write('    :target: ../../_images/' +
+            current_doc_file.write('    :target: ../../../_images/' +
                                    doc_tuple[0] +
                                    '-' + doc_tuple[1] + '.svg\n')