From 3b34019f0bda380b173170ace93beaa71873b340 Mon Sep 17 00:00:00 2001 From: Sean McGinnis Date: Thu, 5 Apr 2018 14:05:08 -0500 Subject: [PATCH] Use sphinxcontrib.apidoc for module docs Now that sphinxcontrib.apidoc is available, we should get rid of the custom code we have for generating this information ourselves. This also cleans up some really stale docs that are no longer needed. Change-Id: Iaa9fecc2478326b45b67a2cfd98de5f93f537efe --- cinder/consistencygroup/__init__.py | 0 doc/ext/cinder_autodoc.py | 26 --- doc/find_autodoc_modules.sh | 20 --- doc/generate_autodoc_index.sh | 46 ----- doc/requirements.txt | 1 + doc/source/conf.py | 26 ++- doc/source/contributor/api.rst | 97 ----------- doc/source/contributor/auth.rst | 244 --------------------------- doc/source/contributor/cinder.rst | 118 ------------- doc/source/contributor/database.rst | 54 ------ doc/source/contributor/fakes.rst | 44 ----- doc/source/contributor/gerrit.rst | 2 +- doc/source/contributor/index.rst | 21 +-- doc/source/contributor/scheduler.rst | 61 ------- doc/source/contributor/services.rst | 55 ------ doc/source/contributor/volume.rst | 64 ------- tox.ini | 6 +- 17 files changed, 24 insertions(+), 861 deletions(-) delete mode 100644 cinder/consistencygroup/__init__.py delete mode 100644 doc/ext/cinder_autodoc.py delete mode 100755 doc/find_autodoc_modules.sh delete mode 100755 doc/generate_autodoc_index.sh delete mode 100644 doc/source/contributor/api.rst delete mode 100644 doc/source/contributor/auth.rst delete mode 100644 doc/source/contributor/cinder.rst delete mode 100644 doc/source/contributor/database.rst delete mode 100644 doc/source/contributor/fakes.rst delete mode 100644 doc/source/contributor/scheduler.rst delete mode 100644 doc/source/contributor/services.rst delete mode 100644 doc/source/contributor/volume.rst diff --git a/cinder/consistencygroup/__init__.py b/cinder/consistencygroup/__init__.py deleted file mode 100644 index e69de29bb2d..00000000000 diff --git a/doc/ext/cinder_autodoc.py b/doc/ext/cinder_autodoc.py deleted file mode 100644 index 1d49fbbe58e..00000000000 --- a/doc/ext/cinder_autodoc.py +++ /dev/null @@ -1,26 +0,0 @@ -# Licensed under the Apache License, Version 2.0 (the "License"); you may -# not use this file except in compliance with the License. You may obtain -# a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT -# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the -# License for the specific language governing permissions and limitations -# under the License. - -from __future__ import print_function - -import gettext -import os - -gettext.install('cinder') - -from cinder import utils - - -def setup(app): - print("**Autodocumenting from %s" % os.path.abspath(os.curdir)) - rv = utils.execute('./doc/generate_autodoc_index.sh') - print(rv[0]) diff --git a/doc/find_autodoc_modules.sh b/doc/find_autodoc_modules.sh deleted file mode 100755 index fb7e451a08c..00000000000 --- a/doc/find_autodoc_modules.sh +++ /dev/null @@ -1,20 +0,0 @@ -#!/bin/bash - -CINDER_DIR='cinder/' # include trailing slash -DOCS_DIR='source' - -modules='' -for x in `find ${CINDER_DIR} -name '*.py' | grep -v cinder/tests`; do - if [ `basename ${x} .py` == "__init__" ] ; then - continue - fi - relative=cinder.`echo ${x} | sed -e 's$^'${CINDER_DIR}'$$' -e 's/.py$//' -e 's$/$.$g'` - modules="${modules} ${relative}" -done - -for mod in ${modules} ; do - if [ ! -f "${DOCS_DIR}/${mod}.rst" ]; - then - echo ${mod} - fi -done diff --git a/doc/generate_autodoc_index.sh b/doc/generate_autodoc_index.sh deleted file mode 100755 index 335f72cfa34..00000000000 --- a/doc/generate_autodoc_index.sh +++ /dev/null @@ -1,46 +0,0 @@ -#!/bin/sh - -SOURCEDIR=doc/source/contributor/api - -if [ ! -d ${SOURCEDIR} ] ; then - mkdir -p ${SOURCEDIR} -fi - -for x in `./doc/find_autodoc_modules.sh`; -do - echo "Generating ${SOURCEDIR}/${x}.rst" - echo "${SOURCEDIR}/${x}.rst" >> .autogenerated - heading="The :mod:\`${x}\` Module" - # Figure out how long the heading is - # and make sure to emit that many '=' under - # it to avoid heading format errors - # in Sphinx. - heading_len=$(echo "$heading" | wc -c) - underline=$(head -c $heading_len < /dev/zero | tr '\0' '=') - ( cat < ${SOURCEDIR}/${x}.rst - -done - -if [ ! -f ${SOURCEDIR}/autoindex.rst ] ; then - - cat > ${SOURCEDIR}/autoindex.rst <> ${SOURCEDIR}/autoindex.rst - done - - echo ${SOURCEDIR}/autoindex.rst >> .autogenerated -fi diff --git a/doc/requirements.txt b/doc/requirements.txt index 1f767ab3f2f..b93ed8217e2 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -9,3 +9,4 @@ mock>=2.0.0 # BSD os-api-ref>=1.4.0 # Apache-2.0 ddt>=1.0.1 # MIT fixtures>=3.0.0 # Apache-2.0/BSD +sphinxcontrib-apidoc>=0.2.0 # BSD diff --git a/doc/source/conf.py b/doc/source/conf.py index 325e41b0bbd..00b32ba6ff7 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -52,8 +52,7 @@ sys.path.insert(0, os.path.abspath('./')) # They can be extensions coming with Sphinx (named 'sphinx.ext.*') # or your custom ones. -extensions = ['sphinx.ext.autodoc', - 'sphinx.ext.coverage', +extensions = ['sphinx.ext.coverage', 'sphinx.ext.graphviz', 'openstackdocstheme', 'stevedore.sphinxext', @@ -61,8 +60,25 @@ extensions = ['sphinx.ext.autodoc', 'ext.cinder_driverlist', 'oslo_policy.sphinxext', 'oslo_policy.sphinxpolicygen', + 'sphinxcontrib.apidoc', ] +# sphinxcontrib.apidoc options +apidoc_module_dir = '../../cinder' +apidoc_output_dir = 'contributor/api' +apidoc_excluded_paths = [ + 'tests/*', + 'tests', + 'db/sqlalchemy/*', + 'db/sqlalchemy', + 'volume/drivers/*', + 'volume/drivers', + 'zonemanager/drivers/*', + 'zonemanager/drivers', + 'backup/drivers/*', + 'backup/drivers'] +apidoc_separate_modules = True + config_generator_config_file = ( '../../tools/config/cinder-config-generator.conf') sample_config_basename = '_static/cinder' @@ -71,12 +87,6 @@ policy_generator_config_file = ( '../../tools/config/cinder-policy-generator.conf') sample_policy_basename = '_static/cinder' -# autodoc generation is a bit aggressive and a nuisance -# when doing heavy text edit cycles. Execute "export SPHINX_DEBUG=1" -# in your terminal to disable -if not os.getenv('SPHINX_DEBUG'): - extensions += ['ext.cinder_autodoc'] - todo_include_todos = True # Add any paths that contain templates here, relative to this directory. diff --git a/doc/source/contributor/api.rst b/doc/source/contributor/api.rst deleted file mode 100644 index 350f9a4aa64..00000000000 --- a/doc/source/contributor/api.rst +++ /dev/null @@ -1,97 +0,0 @@ -.. - Copyright 2010-2011 United States Government as represented by the - Administrator of the National Aeronautics and Space Administration. - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -API Endpoint -============ - -Cinder has a system for managing multiple APIs on different subdomains. -Currently there is support for the OpenStack API. - -Common Components ------------------ - -The :mod:`cinder.api` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: cinder.api - :noindex: - :members: - :undoc-members: - :show-inheritance: - - -Tests ------ - -The :mod:`api` Module -~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: cinder.tests.unit.api - :noindex: - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`api.fakes` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: cinder.tests.unit.api.fakes - :noindex: - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`api.openstack` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: cinder.tests.unit.api.openstack - :noindex: - :members: - :undoc-members: - :show-inheritance: - - -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.unit.api.middleware.test_auth - :noindex: - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`test_faults` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: cinder.tests.unit.api.middleware.test_faults - :noindex: - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/source/contributor/auth.rst b/doc/source/contributor/auth.rst deleted file mode 100644 index 58af2db7523..00000000000 --- a/doc/source/contributor/auth.rst +++ /dev/null @@ -1,244 +0,0 @@ -.. - Copyright 2010-2011 United States Government as represented by the - Administrator of the National Aeronautics and Space Administration. - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -.. _auth: - -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: - :members: - :undoc-members: - :show-inheritance: - - -Tests ------ - - -The :mod:`middleware.test_auth` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: cinder.tests.unit.api.middleware.test_auth - :noindex: - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`test_quota` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: cinder.tests.unit.test_quota - :noindex: - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`test_quota_utils` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: cinder.tests.unit.test_quota_utils - :noindex: - :members: - :undoc-members: - :show-inheritance: - - -Legacy Docs ------------ - -Cinder provides RBAC (Role-based access control) of the AWS-type APIs. We define the following roles: - -Roles-Based Access Control of AWS-style APIs using SAML Assertions -“Achieving FIPS 199 Moderate certification of a hybrid cloud environment using CloudAudit and declarative C.I.A. classifications” - - -Introduction ------------- - -We will investigate one method for integrating an AWS-style API with US eAuthentication-compatible federated authentication systems, to achieve access controls and limits based on traditional operational roles. -Additionally, we will look at how combining this approach, with an implementation of the CloudAudit APIs, will allow us to achieve a certification under FIPS 199 Moderate classification for a hybrid cloud environment. - - -Relationship of US eAuth to RBAC --------------------------------- - -Typical implementations of US eAuth authentication systems are structured as follows:: - - [ MS Active Directory or other federated LDAP user store ] - --> backends to… - [ SUN Identity Manager or other SAML Policy Controller ] - --> maps URLs to groups… - [ Apache Policy Agent in front of eAuth-secured Web Application ] - -In more ideal implementations, the remainder of the application-specific account information is stored either in extended schema on the LDAP server itself, via the use of a translucent LDAP proxy, or in an independent datastore keyed off of the UID provided via SAML assertion. - -.. _auth_roles: - - -Roles ------ - -AWS API calls are traditionally secured via Access and Secret Keys, which are used to sign API calls, along with traditional timestamps to prevent replay attacks. The APIs can be logically grouped into sets that align with five typical roles: - -* Base User -* System Administrator/Developer (currently have the same permissions) -* Network Administrator -* Project Manager -* Cloud Administrator/IT-Security (currently have the same permissions) - -There is an additional, conceptual end-user that may or may not have API access: - -* (EXTERNAL) End-user / Third-party User - -Basic operations are available to any : - -* Describe Instances -* Describe Images -* Describe Volumes -* Describe Keypairs -* Create Keypair -* Delete Keypair -* Create, Upload, Delete: Buckets and Keys (Object Store) - -System Administrators/Developers/Project Manager: - -* Create, Attach, Delete Volume (Block Store) -* Launch, Reboot, Terminate Instance -* Register/Unregister Machine Image (project-wide) -* Request / Review CloudAudit Scans - -Project Manager: - -* Add and remove other users (currently no api) -* Set roles (currently no api) - -Network Administrator: - -* Change Machine Image properties (public / private) -* Change Firewall Rules, define Security Groups -* Allocate, Associate, Deassociate Public IP addresses - -Cloud Administrator/IT-Security: - -* All permissions - - -Enhancements ------------- - -* SAML Token passing -* REST interfaces -* SOAP interfaces - -Wrapping the SAML token into the API calls. -Then store the UID (fetched via backchannel) into the instance metadata, providing end-to-end auditability of ownership and responsibility, without PII. - - -CloudAudit APIs ---------------- - -* Request formats -* Response formats -* Stateless asynchronous queries - -CloudAudit queries may spawn long-running processes (similar to launching instances, etc.) They need to return a ReservationId in the same fashion, which can be returned in further queries for updates. -RBAC of CloudAudit API calls is critical, since detailed system information is a system vulnerability. - - -Type declarations ------------------ -* Data declarations – Volumes and Objects -* System declarations – Instances - -Existing API calls to launch instances specific a single, combined “type” flag. We propose to extend this with three additional type declarations, mapping to the “Confidentiality, Integrity, Availability” classifications of FIPS 199. An example API call would look like:: - - RunInstances type=m1.large number=1 secgroup=default key=mykey confidentiality=low integrity=low availability=low - -These additional parameters would also apply to creation of block storage volumes (along with the existing parameter of 'size'), and creation of object storage 'buckets'. (C.I.A. classifications on a bucket would be inherited by the keys within this bucket.) - - -Request Brokering ------------------ - -* Cloud Interop -* IMF Registration / PubSub -* Digital C&A - -Establishing declarative semantics for individual API calls will allow the cloud environment to seamlessly proxy these API calls to external, third-party vendors – when the requested CIA levels match. - -See related work within the Infrastructure 2.0 working group for more information on how the IMF Metadata specification could be utilized to manage registration of these vendors and their C&A credentials. - - -Dirty Cloud - Hybrid Data Centers ---------------------------------- - -* CloudAudit bridge interfaces -* Anything in the ARP table - -A hybrid cloud environment provides dedicated, potentially co-located physical hardware with a network interconnect to the project or user's cloud virtual network. - -This interconnect is typically a bridged VPN connection. Any machines that can be bridged into a hybrid environment in this fashion (at Layer 2) must implement a minimum version of the CloudAudit spec, such that they can be queried to provide a complete picture of the IT-sec runtime environment. - -Network discovery protocols (ARP, CDP) can be applied in this case, and existing protocols (SNMP location data, DNS LOC records) overloaded to provide CloudAudit information. - - -The Details ------------ - -* Preliminary Roles Definitions -* Categorization of available API calls -* SAML assertion vocabulary - - -System limits -------------- - -The following limits need to be defined and enforced: - -* Total number of instances allowed (user / project) -* Total number of instances, per instance type (user / project) -* Total number of volumes (user / project) -* Maximum size of volume -* Cumulative size of all volumes -* Total use of object storage (GB) -* Total number of Public IPs - - -Further Challenges ------------------- - -* Prioritization of users / jobs in shared computing environments -* Incident response planning -* Limit launch of instances to specific security groups based on AMI -* Store AMIs in LDAP for added property control diff --git a/doc/source/contributor/cinder.rst b/doc/source/contributor/cinder.rst deleted file mode 100644 index 02d383eea63..00000000000 --- a/doc/source/contributor/cinder.rst +++ /dev/null @@ -1,118 +0,0 @@ -.. - Copyright 2010-2011 United States Government as represented by the - Administrator of the National Aeronautics and Space Administration. - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -Common and Misc Libraries -========================= - -Libraries common throughout Cinder or just ones that haven't been categorized -very well yet. - - -The :mod:`cinder.context` Module --------------------------------- - -.. automodule:: cinder.context - :noindex: - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`cinder.exception` Module ----------------------------------- - -.. automodule:: cinder.exception - :noindex: - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`cinder.common.config` Module --------------------------------------- - -.. automodule:: cinder.common.config - :noindex: - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`cinder.rpc` Module ----------------------------- - -.. automodule:: cinder.rpc - :noindex: - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`cinder.test` Module ------------------------------ - -.. automodule:: cinder.test - :noindex: - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`cinder.utils` Module ------------------------------- - -.. automodule:: cinder.utils - :noindex: - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`cinder.wsgi` Module ------------------------------ - -.. automodule:: cinder.wsgi - :noindex: - :members: - :undoc-members: - :show-inheritance: - - -Tests ------ - - -The :mod:`conf_fixture` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. 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: - :show-inheritance: - - diff --git a/doc/source/contributor/database.rst b/doc/source/contributor/database.rst deleted file mode 100644 index 6c3c8ad956c..00000000000 --- a/doc/source/contributor/database.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. - Copyright 2010-2011 United States Government as represented by the - Administrator of the National Aeronautics and Space Administration. - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -The Database Layer -================== - -The :mod:`cinder.db.api` Module -------------------------------- - -.. automodule:: cinder.db.api - :noindex: - :members: - :undoc-members: - :show-inheritance: - - -The Sqlalchemy Driver ---------------------- - -The :mod:`cinder.db.sqlalchemy.api` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: cinder.db.sqlalchemy.api - :noindex: - -The :mod:`cinder.db.sqlalchemy.models` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: cinder.db.sqlalchemy.models - :noindex: - :members: - :undoc-members: - :show-inheritance: - - -Tests ------ - -Tests are lacking for the db api layer and for the sqlalchemy driver. -Failures in the drivers would be detected in other test cases, though. diff --git a/doc/source/contributor/fakes.rst b/doc/source/contributor/fakes.rst deleted file mode 100644 index c65295a943e..00000000000 --- a/doc/source/contributor/fakes.rst +++ /dev/null @@ -1,44 +0,0 @@ -.. - Copyright 2010-2011 United States Government as represented by the - Administrator of the National Aeronautics and Space Administration. - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -Fake Drivers -============ - -TODO: document general info about fakes - -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 -------------------------------------------------------------- - -.. autoclass:: cinder.tests.unit.test_service.FakeManager - :noindex: - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`cinder.tests.unit.api.fakes` Module ---------------------------------------------- - -.. automodule:: cinder.tests.unit.api.fakes - :noindex: - :members: - :undoc-members: - :show-inheritance: - diff --git a/doc/source/contributor/gerrit.rst b/doc/source/contributor/gerrit.rst index 97f8aa4aecf..e5556548d80 100644 --- a/doc/source/contributor/gerrit.rst +++ b/doc/source/contributor/gerrit.rst @@ -87,6 +87,6 @@ to the submitter with a request for the addition of unit test. does not include a unit test execution. .. _Review guidelines: https://docs.openstack.org/doc-contrib-guide/docs-review-guidelines.html -.. _Gerrit: https://review.openstack.org/#/q/project:openstack/cinder+status:open +.. _Gerrit: https://review.openstack.org/#/q/project:openstack/cinder+status:open .. _Development Workflow: https://docs.openstack.org/infra/manual/developers.html#development-workflow .. _Gerrit Workflow Quick Reference: https://docs.openstack.org/infra/manual/developers.html#development-workflow diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 1c636480686..0a0395978bd 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -72,26 +72,7 @@ Other Resources jenkins releasenotes -API Reference -------------- -.. toctree:: - :maxdepth: 3 - - ./api/autoindex - -Module Reference ----------------- -.. toctree:: - :maxdepth: 3 - - services - database - volume - auth - api - scheduler - fakes - cinder + Module Reference Indices and tables ------------------ diff --git a/doc/source/contributor/scheduler.rst b/doc/source/contributor/scheduler.rst deleted file mode 100644 index f5b33c96b14..00000000000 --- a/doc/source/contributor/scheduler.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. - Copyright 2010-2011 United States Government as represented by the - Administrator of the National Aeronautics and Space Administration. - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -Scheduler -========= - -The :mod:`cinder.scheduler.manager` Module ------------------------------------------- - -.. automodule:: cinder.scheduler.manager - :noindex: - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`cinder.scheduler.driver` Module ------------------------------------------ - -.. automodule:: cinder.scheduler.driver - :noindex: - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`cinder.scheduler.filter_scheduler` Driver ---------------------------------------------------- - -.. automodule:: cinder.scheduler.filter_scheduler - :noindex: - :members: - :undoc-members: - :show-inheritance: - - -Tests ------ - -The :mod:`cinder.tests.unit.scheduler` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: cinder.tests.unit.scheduler - :noindex: - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/source/contributor/services.rst b/doc/source/contributor/services.rst deleted file mode 100644 index e2dd6d2b05b..00000000000 --- a/doc/source/contributor/services.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. - Copyright 2010-2011 United States Government as represented by the - Administrator of the National Aeronautics and Space Administration. - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -.. _service_manager_driver: - -Services, Managers and Drivers -============================== - -The responsibilities of Services, Managers, and Drivers, can be a bit confusing to people that are new to cinder. This document attempts to outline the division of responsibilities to make understanding the system a little bit easier. - -Currently, Managers and Drivers are specified by flags and loaded using utils.load_object(). This method allows for them to be implemented as singletons, classes, modules or objects. As long as the path specified by the flag leads to an object (or a callable that returns an object) that responds to getattr, it should work as a manager or driver. - - -The :mod:`cinder.service` Module --------------------------------- - -.. automodule:: cinder.service - :noindex: - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`cinder.manager` Module --------------------------------- - -.. automodule:: cinder.manager - :noindex: - :members: - :undoc-members: - :show-inheritance: - - -Implementation-Specific Drivers -------------------------------- - -A manager will generally load a driver for some of its tasks. The driver is responsible for specific implementation details. Anything running shell commands on a host, or dealing with other non-python code should probably be happening in a driver. - -Drivers should minimize touching the database, although it is currently acceptable for implementation specific data. This may be reconsidered at some point. - -It usually makes sense to define an Abstract Base Class for the specific driver (i.e. VolumeDriver), to define the methods that a different driver would need to implement. diff --git a/doc/source/contributor/volume.rst b/doc/source/contributor/volume.rst deleted file mode 100644 index 8316873f62b..00000000000 --- a/doc/source/contributor/volume.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. - Copyright 2010-2011 United States Government as represented by the - Administrator of the National Aeronautics and Space Administration. - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -Storage Volumes, Disks -====================== - -.. note:: - TODO(todd or vish): rework after iSCSI merge (see 'Old Docs') (todd or vish) - - -The :mod:`cinder.volume.manager` Module ---------------------------------------- - -.. automodule:: cinder.volume.manager - :noindex: - :members: - :undoc-members: - :show-inheritance: - -The :mod:`cinder.volume.driver` Module --------------------------------------- - -.. automodule:: cinder.volume.driver - :noindex: - :members: - :undoc-members: - :show-inheritance: - -Tests ------ - -The :mod:`cinder.tests.unit.volume` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: cinder.tests.unit.volume - :noindex: - :members: - :undoc-members: - :show-inheritance: - -Old Docs --------- - -Cinder uses iSCSI to export storage volumes from multiple storage nodes. These iSCSI exports are attached (using libvirt) directly to running instances. - -Cinder volumes are exported over the primary system VLAN (usually VLAN 1), and not over individual VLANs. - -The underlying volumes by default are LVM logical volumes, created on demand within a single large volume group. - - diff --git a/tox.ini b/tox.ini index fdb0aaa52ea..c99b5f00c25 100644 --- a/tox.ini +++ b/tox.ini @@ -30,10 +30,10 @@ whitelist_externals = passenv = *_proxy *_PROXY [testenv:api-ref] -# (sheel)This environment is called from CI scripts to test and publish -# the API Ref to developer.openstack.org. whitelist_externals = rm -deps = -r{toxinidir}/test-requirements.txt +deps = + -c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt} + -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/