openstack/cinder
Code Issues Proposed changes

Fix doc and source documentation errors and warning

Browse Source 
Solve warnings and errors from build_sphinx. Fix rst doc files
and source code docstring issues.

Closes-Bug: #1557047

Change-Id: Ib59df2681c98716c786ff0edf6d7cfcc3e8fe5ec
Signed-off-by: Danny Al-Gaaf <danny.al-gaaf@bisect.de>
This commit is contained in:
Danny Al-Gaaf
2016-03-14 23:09:12 +01:00
parent 3c4b65afc6
commit 1323339d33
90 changed files with 1025 additions and 859 deletions
Download Patch File Download Diff File Expand all files Collapse all files

54
doc/source/devref/api.rst
View File

@@ -33,88 +33,64 @@ The :mod:`cinder.api` Module
:undoc-members:
:show-inheritance:
OpenStack API
-------------
The :mod:`openstack` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: cinder.api.openstack
:noindex:
:members:
:undoc-members:
:show-inheritance:
Tests
-----
The :mod:`api_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The :mod:`api` Module
~~~~~~~~~~~~~~~~~~~~~
.. automodule:: cinder.tests.api_unittest
.. automodule:: cinder.tests.unit.api
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`api_integration` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: cinder.tests.api_integration
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`cloud_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: cinder.tests.cloud_unittest
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`api.fakes` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: cinder.tests.api.fakes
.. automodule:: cinder.tests.unit.api.fakes
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`api.test_wsgi` Module
The :mod:`api.openstack` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: cinder.tests.api.test_wsgi
.. automodule:: cinder.tests.unit.api.openstack
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`test_api` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: cinder.tests.api.openstack.test_api
The :mod:`api.openstack.test_wsgi` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: cinder.tests.unit.api.openstack.test_wsgi
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`test_auth` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: cinder.tests.api.openstack.test_auth
.. automodule:: cinder.tests.unit.api.middleware.test_auth
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`test_faults` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: cinder.tests.api.openstack.test_faults
.. automodule:: cinder.tests.unit.api.middleware.test_faults
:noindex:
:members:
:undoc-members:

2
doc/source/devref/api_microversion_dev.rst
View File

@@ -13,7 +13,7 @@ is done with an HTTP header ``OpenStack-API-Version`` which
is a monotonically increasing semantic version number starting from
``3.0``. Each service that uses microversions will share this header, so
the Volume service will need to specifiy ``volume``:
``OpenStack-API-Version: volume 3.0``
``OpenStack-API-Version: volume 3.0``
If a user makes a request without specifying a version, they will get
the ``DEFAULT_API_VERSION`` as defined in

53
doc/source/devref/auth.rst
View File

@@ -20,8 +20,18 @@
Authentication and Authorization
================================
The :mod:`cinder.api.middleware.auth` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: cinder.api.middleware.auth
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`cinder.quota` Module
------------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: cinder.quota
:noindex:
@@ -30,57 +40,34 @@ The :mod:`cinder.quota` Module
:show-inheritance:
The :mod:`cinder.auth.signer` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: cinder.auth.signer
:noindex:
:members:
:undoc-members:
:show-inheritance:
Auth Manager
------------
The :mod:`cinder.auth.manager` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: cinder.auth.manager
:noindex:
:members:
:undoc-members:
:show-inheritance:
Tests
-----
The :mod:`auth_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The :mod:`middleware.test_auth` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: cinder.tests.auth_unittest
.. automodule:: cinder.tests.unit.api.middleware.test_auth
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`access_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The :mod:`test_quota` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: cinder.tests.access_unittest
.. automodule:: cinder.tests.unit.test_quota
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`quota_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The :mod:`test_quota_utils` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: cinder.tests.quota_unittest
.. automodule:: cinder.tests.unit.test_quota_utils
:noindex:
:members:
:undoc-members:

90
doc/source/devref/cinder.rst
View File

@@ -22,16 +22,6 @@ Libraries common throughout Cinder or just ones that haven't been categorized
very well yet.
The :mod:`cinder.adminclient` Module
------------------------------------
.. automodule:: cinder.adminclient
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`cinder.context` Module
--------------------------------
@@ -53,7 +43,7 @@ The :mod:`cinder.exception` Module
The :mod:`cinder.common.config` Module
------------------------------
--------------------------------------
.. automodule:: cinder.common.config
:noindex:
@@ -62,16 +52,6 @@ The :mod:`cinder.common.config` Module
:show-inheritance:
The :mod:`cinder.process` Module
--------------------------------
.. automodule:: cinder.process
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`cinder.rpc` Module
----------------------------
@@ -82,16 +62,6 @@ The :mod:`cinder.rpc` Module
:show-inheritance:
The :mod:`cinder.server` Module
-------------------------------
.. automodule:: cinder.server
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`cinder.test` Module
-----------------------------
@@ -112,16 +82,6 @@ The :mod:`cinder.utils` Module
:show-inheritance:
The :mod:`cinder.validate` Module
---------------------------------
.. automodule:: cinder.validate
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`cinder.wsgi` Module
-----------------------------
@@ -136,9 +96,9 @@ Tests
-----
The :mod:`declare_conf` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: cinder.tests.declare_conf
.. automodule:: cinder.tests.unit.declare_conf
:noindex:
:members:
:undoc-members:
@@ -146,29 +106,19 @@ The :mod:`declare_conf` Module
The :mod:`conf_fixture` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: cinder.tests.conf_fixture
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`process_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: cinder.tests.process_unittest
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`rpc_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: cinder.tests.rpc_unittest
.. automodule:: cinder.tests.unit.conf_fixture
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`test_rpc` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: cinder.tests.unit.test_rpc
:noindex:
:members:
:undoc-members:
@@ -178,17 +128,7 @@ The :mod:`rpc_unittest` Module
The :mod:`runtime_conf` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: cinder.tests.runtime_conf
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`validator_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: cinder.tests.validator_unittest
.. automodule:: cinder.tests.unit.runtime_conf
:noindex:
:members:
:undoc-members:

9
doc/source/devref/database.rst
View File

@@ -46,15 +46,6 @@ The :mod:`cinder.db.sqlalchemy.models` Module
:undoc-members:
:show-inheritance:
The :mod:`cinder.db.sqlalchemy.session` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: cinder.db.sqlalchemy.session
:noindex:
:members:
:undoc-members:
:show-inheritance:
Tests
-----

53
doc/source/devref/fakes.rst
View File

@@ -23,61 +23,20 @@ Fake Drivers
When the real thing isn't available and you have some development to do these
fake implementations of various drivers let you get on with your day.
The :class:`cinder.tests.unit.test_service.FakeManager` Class
-------------------------------------------------------------
The :mod:`cinder.virt.fake` Module
----------------------------------
.. automodule:: cinder.virt.fake
.. autoclass:: cinder.tests.unit.test_service.FakeManager
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`cinder.auth.fakeldap` Module
--------------------------------------
The :mod:`cinder.tests.unit.api.fakes` Module
---------------------------------------------
.. automodule:: cinder.auth.fakeldap
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`cinder.testing.fake.rabbit` Module
--------------------------------------------
.. automodule:: cinder.testing.fake.rabbit
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :class:`cinder.volume.driver.FakeAOEDriver` Class
-----------------------------------------------------
.. autoclass:: cinder.volume.driver.FakeAOEDriver
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :class:`cinder.tests.service_unittest.FakeManager` Class
------------------------------------------------------------
.. autoclass:: cinder.tests.service_unittest.FakeManager
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`cinder.tests.api.openstack.fakes` Module
--------------------------------------------------
.. automodule:: cinder.tests.api.openstack.fakes
.. automodule:: cinder.tests.unit.api.fakes
:noindex:
:members:
:undoc-members:

71
doc/source/devref/migration.rst
View File

@@ -49,35 +49,37 @@ regardless if the back-ends are located on the same c-vol node or not.
How to do volume migration via CLI
----------------------------------
Scenario 1 of volume migration is done via the following command from
the CLI:
cinder migrate [--force-host-copy [<True|False>]]
[--lock-volume [<True|False>]]
<volume> <host>
Mandatory arguments:
<volume> ID of volume to migrate.
<host> Destination host. The format of host is
host@backend#POOL, while 'host' is the host
name of the volume node, 'backend' is the back-end
name and 'POOL' is a logical concept to describe
a set of storage resource, residing in the
back-end. If the back-end does not have specified
pools, 'POOL' needs to be set with the same name
as 'backend'.
the CLI::
Optional arguments:
--force-host-copy [<True|False>]
Enables or disables generic host-based force-
migration, which bypasses the driver optimization.
Default=False.
--lock-volume [<True|False>]
Enables or disables the termination of volume
migration caused by other commands. This option
applies to the available volume. True means it locks
the volume state and does not allow the migration to
be aborted. The volume status will be in maintenance
during the migration. False means it allows the volume
migration to be aborted. The volume status is still in
the original status. Default=False.
cinder migrate [--force-host-copy [<True|False>]]
[--lock-volume [<True|False>]]
<volume> <host>
Mandatory arguments:
<volume> ID of volume to migrate.
<host> Destination host. The format of host is
host@backend#POOL, while 'host' is the host
name of the volume node, 'backend' is the back-end
name and 'POOL' is a logical concept to describe
a set of storage resource, residing in the
back-end. If the back-end does not have specified
pools, 'POOL' needs to be set with the same name
as 'backend'.
Optional arguments:
--force-host-copy [<True|False>]
Enables or disables generic host-based force-
migration, which bypasses the driver optimization.
Default=False.
--lock-volume [<True|False>]
Enables or disables the termination of volume
migration caused by other commands. This option
applies to the available volume. True means it locks
the volume state and does not allow the migration to
be aborted. The volume status will be in maintenance
during the migration. False means it allows the volume
migration to be aborted. The volume status is still in
the original status. Default=False.
Important note: Currently, error handling for failed migration operations is
under development in Cinder. If we would like the volume migration to finish
@@ -89,12 +91,13 @@ request of another action comes.
Scenario 2 of volume migration can be done via the following command
from the CLI:
cinder retype --migration-policy on-demand
<volume> <volume-type>
Mandatory arguments:
<volume> Name or ID of volume for which to modify type.
<volume-type> New volume type.
from the CLI::
cinder retype --migration-policy on-demand
<volume> <volume-type>
Mandatory arguments:
<volume> Name or ID of volume for which to modify type.
<volume-type> New volume type.
Source volume type and destination volume type must be different and
they must refer to different back-ends.

1
doc/source/devref/replication.rst
View File

@@ -132,6 +132,7 @@ They include::
Additionally we have freeze/thaw methods that will act on the scheduler
but may or may not require something from the driver::
freeze_backend(self, context)
thaw_backend(self, context)

2
doc/source/devref/rolling.upgrades.rst
View File

@@ -243,7 +243,7 @@ will get updated before clients by stating the recommended order of upgrades
for that release.
RPC payload changes (oslo.versionedobjects)
------------------------------------------
-------------------------------------------
`oslo.versionedobjects
<http://docs.openstack.org/developer/oslo.versionedobjects>`_ is a library that

8
doc/source/devref/scheduler.rst
View File

@@ -39,7 +39,7 @@ The :mod:`cinder.scheduler.driver` Module
The :mod:`cinder.scheduler.filter_scheduler` Driver
-----------------------------------------
---------------------------------------------------
.. automodule:: cinder.scheduler.filter_scheduler
:noindex:
@@ -51,10 +51,10 @@ The :mod:`cinder.scheduler.filter_scheduler` Driver
Tests
-----
The :mod:`scheduler_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The :mod:`cinder.tests.unit.scheduler` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: cinder.tests.scheduler_unittest
.. automodule:: cinder.tests.unit.scheduler
:noindex:
:members:
:undoc-members:

9
doc/source/devref/unit_tests.rst
View File

@@ -11,6 +11,7 @@ Running the tests
There are a number of ways to run unit tests currently, and there's a combination
of frameworks used depending on what commands you use. The preferred method
is to use tox, which calls ostestr via the tox.ini file. To run all tests simply run::
tox
This will create a virtual environment, load all the packages from test-requirements.txt
@@ -76,6 +77,7 @@ Because ``run_tests.sh`` is a wrapper around testr, it also accepts the same
flags as testr. See the `testr documentation`_ for details about
these additional flags.
.. _testr documentation: https://testrepository.readthedocs.org/en/latest/
.. _nose options documentation: http://readthedocs.org/docs/nose/en/latest/usage.html#options
Running a subset of tests
@@ -134,7 +136,7 @@ If you do not wish to use a virtualenv at all, use the flag::
Database
--------
Some of the unit tests make queries against an sqlite database [#f3]_. By
Some of the unit tests make queries against an sqlite database. By
default, the test database (``tests.sqlite``) is deleted and recreated each
time ``run_tests.sh`` is invoked (This is equivalent to using the
``-r, --recreate-db`` flag). To reduce testing time if a database already
@@ -152,7 +154,7 @@ Gotchas
**Running Tests from Shared Folders**
If you are running the unit tests from a shared folder, you may see tests start
to fail or stop completely as a result of Python lockfile issues [#f4]_. You
to fail or stop completely as a result of Python lockfile issues. You
can get around this by manually setting or updating the following line in
``cinder/tests/conf_fixture.py``::
@@ -173,7 +175,8 @@ a shared folder.
You will need to install:
python3-dev
in order to get py34 tests to run. If you do not have this, you will get the following::
netifaces.c:1:20: fatal error: Python.h: No such file or directory
netifaces.c:1:20: fatal error: Python.h: No such file or directory
#include <Python.h>
^
compilation terminated.

7
doc/source/devref/volume.rst
View File

@@ -38,15 +38,14 @@ The :mod:`cinder.volume.driver` Module
:members:
:undoc-members:
:show-inheritance:
:exclude-members: FakeAOEDriver
Tests
-----
The :mod:`volume_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The :mod:`cinder.tests.unit.volume` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: cinder.tests.volume_unittest
.. automodule:: cinder.tests.unit.volume
:noindex:
:members:
:undoc-members: