Follow the new PTI for document build

For compliance with the Project Testing Interface as described in:
https://governance.openstack.org/tc/reference/project-testing-interface.html

For more details information, please refer to:
http://lists.openstack.org/pipermail/openstack-dev/2017-December/125710.html
http://lists.openstack.org/pipermail/openstack-dev/2018-March/128594.html

Co-Authored-By: Hongbin Lu <hongbin034@gmail.com>

Change-Id: I94afabfc634ae22fb6e0e4ab2e1d17810f6f7c80
Closes-Bug: #1758218

doc/requirements.txt

@@ -0,0 +1,9 @@
+# The order of packages is significant, because pip processes them in the order
+# of appearance. Changing the order has an impact on the overall integration
+# process, which may cause wedges in the gate later.
+# this is required for the docs build jobs
+sphinx>=1.6.2 # BSD
+sphinxcontrib-apidoc>=0.2.0 # BSD
+openstackdocstheme>=1.11.0 # Apache-2.0
+reno>=1.8.0  # Apache-2.0
+os-api-ref>=1.0.0 # Apache-2.0

requirements.txt

@@ -5,7 +5,6 @@
 PyYAML>=3.12 # MIT
 eventlet!=0.18.3,!=0.20.1,>=0.18.2 # MIT
 keystonemiddleware>=4.17.0 # Apache-2.0
-pbr!=2.1.0,>=2.0.0 # Apache-2.0
 pecan!=1.0.2,!=1.0.3,!=1.0.4,!=1.2,>=1.0.0 # BSD
 python-etcd>=0.4.3 # MIT License
 python-glanceclient>=2.8.0 # Apache-2.0

setup.cfg

@@ -25,15 +25,6 @@ data_files =
 packages =
     zun
 
-[build_sphinx]
-source-dir = doc/source
-build-dir = doc/build
-all_files = 1
-warning-is-error = 1
-
-[upload_sphinx]
-upload-dir = doc/build/html
-
 [compile_catalog]
 directory = zun/locale
 domain = zun

specs/local-volume-integration.rst

@@ -30,8 +30,8 @@ Proposed change
 ===============
 This spec proposes the following changes.
 
-1. It's unsafe to mount the host directory into the container, so only admin can
-   bind-mount file or directory in local file system into the container.
+1. It's unsafe to mount the host directory into the container, so only admin
+   can bind-mount file or directory in local file system into the container.
 
 2. We leverage the --mount option for cinder volume bindmount. It is better to
    reuse this option for bind-mounting local file system.
@@ -41,8 +41,9 @@ This spec proposes the following changes.
 3. Zun introduces a config (called 'allowed_mount_path.conf').
    Operators can tune this config to restrict the path for bind-mounting.
 
-4. The administrator would be aware that a special container should be scheduled
-   on which nodes. Users may combine --mount and --hint options to create a container.
+4. The administrator would be aware that a special container should be
+   scheduled on which nodes. Users may combine --mount and --hint options to
+   create a container.
 
 Workflow
 =============
@@ -54,13 +55,15 @@ following:
     $ zun run --mount type=local,source=/proc,destination=/proc \
       --hint <key=value> centos
 
-2. After receiving this request, Zun will check if the mount info has local volumes.
-   Then it will check the user has administrator permissions operation.
+2. After receiving this request, Zun will check if the mount info has local
+   volumes. Then it will check the user has administrator permissions
+   operation.
 
-3. Zun will create an item for local volume, and store in the volume_mapping table.
+3. Zun will create an item for local volume, and store in the volume_mapping
+   table.
 
-4. Zun will choose a node by the option --hint, and check the local volume whether in
-   the volume lists in forbidden_volume.conf.
+4. Zun will choose a node by the option --hint, and check the local volume
+   whether in the volume lists in forbidden_volume.conf.
 
 5. Zun will calls Docker API to create a container and use the option "-v".
 
@@ -68,11 +71,12 @@ following:
 
 Security impact
 ---------------
-1. Only admin can bind-mount file or directory in local file system into the container.
+1. Only admin can bind-mount file or directory in local file system into the
+   container.
 
-2. Zun introduces a config (called 'allowed_mount_path.conf') to check the files/directories
-   can be bind-mounted. When the config is unsetted or empty, zun will raise Exception
-   when using the bind-mounted option.
+2. Zun introduces a config (called 'allowed_mount_path.conf') to check the
+   files/directories can be bind-mounted. When the config is unsetted or empty,
+   zun will raise Exception when using the bind-mounted option.
 
 
 Notifications impact

test-requirements.txt

@@ -9,8 +9,6 @@ coverage!=4.4,>=4.0 # Apache-2.0
 mock>=2.0.0 # BSD
 fixtures>=3.0.0 # Apache-2.0/BSD
 hacking!=0.13.0,<0.14,>=0.12.0 # Apache-2.0
-sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
-openstackdocstheme>=1.18.1 # Apache-2.0
 oslotest>=3.2.0 # Apache-2.0
 osprofiler>=1.4.0 # Apache-2.0
 os-testr>=1.0.0 # Apache-2.0
@@ -19,6 +17,4 @@ tempest>=17.1.0 # Apache-2.0
 testresources>=2.0.0 # Apache-2.0/BSD
 testscenarios>=0.4 # Apache-2.0/BSD
 testtools>=2.2.0 # MIT
-reno>=2.5.0 # Apache-2.0
-os-api-ref>=1.4.0 # Apache-2.0
 stestr>=1.0.0 # Apache-2.0

tox.ini

@@ -25,7 +25,7 @@ passenv = http_proxy HTTP_PROXY https_proxy HTTPS_PROXY no_proxy NO_PROXY
 
 [testenv:pep8]
 commands =
-  doc8 -e .rst doc/source/ CONTRIBUTING.rst HACKING.rst README.rst
+  doc8 -e .rst doc/source/ CONTRIBUTING.rst HACKING.rst README.rst --ignore D000
   bash tools/flake8wrap.sh {posargs}
   # The following bandit tests are being skipped:
   # B303 - Use of insecure MD2, MD4, or MD5 hash function.
@@ -49,6 +49,7 @@ commands =
     coverage report
 
 [testenv:docs]
+deps = -r{toxinidir}/doc/requirements.txt
 commands =
     doc8 -e .rst specs/ doc/source/ CONTRIBUTING.rst HACKING.rst README.rst
     sphinx-build -W -d doc/build/doctrees -b html doc/source/ doc/build/html
@@ -95,6 +96,7 @@ commands =
   {toxinidir}/tools/fast8.sh
 
 [testenv:releasenotes]
+deps = -r{toxinidir}/doc/requirements.txt
 commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
 
 [testenv:genconfig]
@@ -107,6 +109,7 @@ commands =
     oslopolicy-sample-generator --config-file etc/zun/zun-policy-generator.conf
 
 [testenv:api-ref]
+deps = -r{toxinidir}/doc/requirements.txt
 commands =
   rm -rf api-ref/build
   sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html

zun/api/controllers/base.py

@@ -160,7 +160,7 @@ class Controller(rest.RestController):
         @min_ver: string representing minimum version
         @max_ver: optional string representing maximum version
         @raises: ApiVersionsIntersect if an version overlap is found between
-            method versions.
+        method versions.
         """
 
         def decorator(f):

zun/api/controllers/v1/__init__.py

@@ -190,4 +190,4 @@ class Controller(controllers_base.Controller):
         return super(Controller, self)._route(args)
 
 
-__all__ = (Controller)
+__all__ = ('Controller',)

zun/api/middleware/__init__.py

@@ -17,5 +17,5 @@ from zun.api.middleware import parsable_error
 AuthTokenMiddleware = auth_token.AuthTokenMiddleware
 ParsableErrorMiddleware = parsable_error.ParsableErrorMiddleware
 
-__all__ = (AuthTokenMiddleware,
-           ParsableErrorMiddleware)
+__all__ = ('AuthTokenMiddleware',
+           'ParsableErrorMiddleware')

zun/common/exception.py

@@ -97,11 +97,11 @@ def wrap_controller_exception(func, func_server_error, func_client_error):
     """This decorator wraps controllers methods to handle exceptions:
 
     - if an unhandled Exception or a ZunException with an error code >=500
-    is catched, raise a http 5xx ClientSideError and correlates it with a log
-    message
+      is catched, raise a http 5xx ClientSideError and correlates it with a log
+      message
 
     - if a ZunException is catched and its error code is <500, raise a http
-    4xx and logs the excp in debug mode
+      4xx and logs the excp in debug mode
 
     """
     @functools.wraps(func)

zun/common/mount.py

@@ -114,7 +114,6 @@ class Mounter(object):
 
         :param devpath: The path of mount device.
         :return: All mountpoints.
-        :rtype: list
         """
         mps = []
         mounts = self.read_mounts()

zun/db/api.py

@@ -43,6 +43,7 @@ def list_containers(context, filters=None, limit=None, marker=None,
 
     Return a list of the specified columns for all containers that match
     the specified filters.
+
     :param context: The security context
     :param filters: Filters to apply. Defaults to None.
     :param limit: Maximum number of containers to return.
@@ -68,6 +69,7 @@ def create_container(context, values):
                    into the Drivers when managing this container. For
                    example:
                    ::
+
                     {
                      'uuid': uuidutils.generate_uuid(),
                      'name': 'example',
@@ -133,6 +135,7 @@ def list_volume_mappings(context, filters=None, limit=None, marker=None,
 
     Return a list of the specified columns for all volume mappings that match
     the specified filters.
+
     :param context: The security context
     :param filters: Filters to apply. Defaults to None.
     :param limit: Maximum number of containers to return.
@@ -268,6 +271,7 @@ def list_zun_services_by_binary(context, binary):
     """List matching zun services.
 
     Return a list of the specified binary.
+
     :param context: The security context
     :param binary: The name of the binary.
     :returns: A list of tuples of the specified binary.
@@ -292,6 +296,7 @@ def pull_image(context, values):
                    into the Drivers when managing this image. For
                    example:
                    ::
+
                     {
                      'uuid': uuidutils.generate_uuid(),
                      'repo': 'hello-world',
@@ -322,6 +327,7 @@ def list_images(context, filters=None,
 
     Return a list of the specified columns for all images that
     match the specified filters.
+
     :param context: The security context
     :param filters: Filters to apply. Defaults to None.
     :param limit: Maximum number of images to return.
@@ -365,6 +371,7 @@ def list_resource_providers(context, filters=None, limit=None, marker=None,
 
     Return a list of the specified columns for all resource providers that
     match the specified filters.
+
     :param context: The security context
     :param filters: Filters to apply. Defaults to None.
     :param limit: Maximum number of resource providers to return.
@@ -437,6 +444,7 @@ def list_resource_classes(context, limit=None, marker=None, sort_key=None,
     """Get matching resource classes.
 
     Return a list of the specified columns for all resource classes.
+
     :param context: The security context
     :param limit: Maximum number of resource classes to return.
     :param marker: the last item of the previous page; we
@@ -507,6 +515,7 @@ def list_inventories(context, filters=None, limit=None, marker=None,
 
     Return a list of the specified columns for all inventories that match
     the specified filters.
+
     :param context: The security context
     :param filters: Filters to apply. Defaults to None.
     :param limit: Maximum number of inventories to return.
@@ -579,6 +588,7 @@ def list_allocations(context, filters=None, limit=None, marker=None,
 
     Return a list of the specified columns for all allocations that match
     the specified filters.
+
     :param context: The security context
     :param filters: Filters to apply. Defaults to None.
     :param limit: Maximum number of allocations to return.
@@ -648,6 +658,7 @@ def list_compute_nodes(context, filters=None, limit=None, marker=None,
 
     Return a list of the specified columns for all compute nodes that match
     the specified filters.
+
     :param context: The security context
     :param filters: Filters to apply. Defaults to None.
     :param limit: Maximum number of compute nodes to return.
@@ -729,6 +740,7 @@ def list_capsules(context, filters=None, limit=None, marker=None,
 
     Return a list of the specified columns for all capsules that match
     the specified filters.
+
     :param context: The security context
     :param filters: Filters to apply. Defaults to None.
     :param limit: Maximum number of capsules to return.
@@ -753,6 +765,7 @@ def create_capsule(context, values):
                    passed into the Drivers when managing this container.
                    For example:
                    ::
+
                     {
                      'uuid': uuidutils.generate_uuid(),
                      'restart_policy': 'always',

zun/objects/__init__.py

@@ -47,22 +47,22 @@ ContainerAction = container_action.ContainerAction
 ContainerActionEvent = container_action.ContainerActionEvent
 
 __all__ = (
-    Container,
-    VolumeMapping,
-    ZunService,
-    Image,
-    ResourceProvider,
-    ResourceClass,
-    NUMANode,
-    NUMATopology,
-    ComputeNode,
-    Capsule,
-    PciDevice,
-    PciDevicePool,
-    Quota,
-    QuotaClass,
-    ContainerPCIRequest,
-    ContainerPCIRequests,
-    ContainerAction,
-    ContainerActionEvent,
+    'Container',
+    'VolumeMapping',
+    'ZunService',
+    'Image',
+    'ResourceProvider',
+    'ResourceClass',
+    'NUMANode',
+    'NUMATopology',
+    'ComputeNode',
+    'Capsule',
+    'PciDevice',
+    'PciDevicePool',
+    'Quota',
+    'QuotaClass',
+    'ContainerPCIRequest',
+    'ContainerPCIRequests',
+    'ContainerAction',
+    'ContainerActionEvent',
 )

zun/objects/quota_class.py

@@ -60,7 +60,7 @@ class QuotaClass(base.ZunPersistentObject, base.ZunObject):
 
         :param context: security context.
         :param class_name: the class name.
-        :return a dict
+        :returns: a dict
         """
         if class_name is None:
             res = dbapi.quota_class_get_default(context)
@@ -89,7 +89,7 @@ class QuotaClass(base.ZunPersistentObject, base.ZunObject):
     def update(self, context=None):
         """Save updates to this QuotaClass.
 
-         Updates will be made column by column based on the result
+        Updates will be made column by column based on the result
         of self.what_changed().
 
         :param context: security context. NOTE: This should only be