openstack/magnum
Code Issues Proposed changes

doc8 all documentation and fix doc style

Browse Source 
Add doc8 to `tox -edocs` command. doc8 will check syntax/style check
rst documents and fail if not compliant.

Change-Id: Id2e9ed1f96cac27dc5e38f828fd2d824dad31c49
This commit is contained in:
Tom Cammann 2015-09-16 16:52:43 +01:00
parent 4381c685b3
commit 6bb1768847
8 changed files with 70 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
HACKING.rst
View File

@ -6,7 +6,7 @@ Magnum Style Commandments
- Step 2: Read on - Step 2: Read on
Magnum Specific Commandments Magnum Specific Commandments
--------------------------- ----------------------------
- [M301] policy.enforce_wsgi decorator must be the first decorator on a method. - [M301] policy.enforce_wsgi decorator must be the first decorator on a method.
- [M322] Method's default argument shouldn't be mutable. - [M322] Method's default argument shouldn't be mutable.

33
contrib/templates/example/README.rst
View File

@ -6,37 +6,42 @@ This project is an example to demonstrate the necessary pieces of a Bay
template. There are three key pieces to a bay template: template. There are three key pieces to a bay template:
1. Heat template - The Heat template that Magnum will use to generate a Bay. 1. Heat template - The Heat template that Magnum will use to generate a Bay.
2. Template definition - Magnum's interface for interacting with the Heat template. 2. Template definition - Magnum's interface for interacting with the Heat
3. Definition Entry Point - Used to advertise the available template definitions. template.
3. Definition Entry Point - Used to advertise the available template
definitions.
The Heat Template The Heat Template
----------------- -----------------
The heat template is where most of the real work happens. The result of the Heat The heat template is where most of the real work happens. The result of the
template should be a full Container Orchestration Environment. Heat template should be a full Container Orchestration Environment.
The Template Definition The Template Definition
----------------------- -----------------------
Template definitions are a mapping of Magnum object attributes and Heat template Template definitions are a mapping of Magnum object attributes and Heat
parameters, along with Magnum consumable template outputs. Each definition also template parameters, along with Magnum consumable template outputs. Each
denotes which Bay Types it can provide. Bay Types are how Magnum determines which definition also denotes which Bay Types it can provide. Bay Types are how
of the enabled Template Definitions it will use for a given Bay. Magnum determines which of the enabled Template Definitions it will use for a
given Bay.
The Definition Entry Point The Definition Entry Point
-------------------------- --------------------------
Entry points are a standard discovery and import mechanism for Python objects. Entry points are a standard discovery and import mechanism for Python objects.
Each Template Definition should have an Entry Point in the `magnum.template_definitions` Each Template Definition should have an Entry Point in the
group. This example exposes it's Template Definition as `example_template = example_template:ExampleTemplate` `magnum.template_definitions` group. This example exposes it's Template
in the `magnum.template_definitions` group. Definition as `example_template = example_template:ExampleTemplate` in the
`magnum.template_definitions` group.
Installing Bay Templates Installing Bay Templates
------------------------ ------------------------
Because Bay Templates are basically Python projects, they can be worked with like Because Bay Templates are basically Python projects, they can be worked with
any other Python project. They can be cloned from version control and installed like any other Python project. They can be cloned from version control and
or uploaded to a package index and installed via utilities such as pip. installed or uploaded to a package index and installed via utilities such as
pip.
Enabling a template is as simple as adding it's Entry Point to the Enabling a template is as simple as adding it's Entry Point to the
`enabled_definitions` config option in magnum.conf.:: `enabled_definitions` config option in magnum.conf.::

3
doc/source/dev/dev-quickstart.rst
View File

@ -33,6 +33,7 @@ Install OS-specific prerequisites::
libmysqlclient-devel libopenssl-devel libxml2-devel \ libmysqlclient-devel libopenssl-devel libxml2-devel \
libxslt-devel postgresql-devel python-devel \ libxslt-devel postgresql-devel python-devel \
gettext-runtime gettext-runtime
Install pip:: Install pip::
curl -s https://bootstrap.pypa.io/get-pip.py | sudo python curl -s https://bootstrap.pypa.io/get-pip.py | sudo python
@ -223,7 +224,7 @@ Note: Reducing node_count will remove all the existing containers on the
nodes that are deleted. nodes that are deleted.
Heat can be used to see detailed information on the status of a stack or Heat can be used to see detailed information on the status of a stack or
specific bay:: specific bay:
To check the list of all bay stacks:: To check the list of all bay stacks::

27
doc/source/objects.rst
View File

@ -18,12 +18,11 @@ Versioned Objects
================= =================
Magnum uses the `oslo.versionedobjects library Magnum uses the `oslo.versionedobjects library
<http://docs.openstack.org/developer/oslo.versionedobjects/index.html>`_ <http://docs.openstack.org/developer/oslo.versionedobjects/index.html>`_ to
to construct an object model that construct an object model that can be communicated via RPC. These objects have
can be communicated via RPC. These objects have a version history and a version history and functionality to convert from one version to a previous
functionality to convert from one version to a previous version. This allows for version. This allows for 2 different levels of the code to still pass objects
2 different levels of the code to still pass objects to each other, as in the to each other, as in the case of rolling upgrades.
case of rolling upgrades.
Object Version Testing Object Version Testing
---------------------- ----------------------
@ -32,10 +31,9 @@ In order to ensure object versioning consistency is maintained,
oslo.versionedobjects has a fixture to aid in testing object versioning. oslo.versionedobjects has a fixture to aid in testing object versioning.
`oslo.versionedobjects.fixture.ObjectVersionChecker `oslo.versionedobjects.fixture.ObjectVersionChecker
<http://docs.openstack.org/developer/oslo.versionedobjects/api/fixture.html#oslo_versionedobjects.fixture.ObjectVersionChecker>`_ <http://docs.openstack.org/developer/oslo.versionedobjects/api/fixture.html#oslo_versionedobjects.fixture.ObjectVersionChecker>`_
generates fingerprints of generates fingerprints of each object, which is a combination of the current
each object, which is a combination of the current version number of the object, version number of the object, along with a hash of the RPC-critical parts of
along with a hash of the RPC-critical parts of the object (fields and remotable the object (fields and remotable methods).
methods).
The tests hold a static mapping of the fingerprints of all objects. When an The tests hold a static mapping of the fingerprints of all objects. When an
object is changed, the hash generated in the test will differ from that held in object is changed, the hash generated in the test will differ from that held in
@ -71,16 +69,17 @@ saying what I changed in the new version::
# Version 1.1: Added 'foo' field # Version 1.1: Added 'foo' field
VERSION = '1.1' VERSION = '1.1'
Now that I have updated the version, I will run the tests again and let the test Now that I have updated the version, I will run the tests again and let the
tell me the fingerprint that I now need to put in the static tree:: test tell me the fingerprint that I now need to put in the static tree::
testtools.matchers._impl.MismatchError: !=: testtools.matchers._impl.MismatchError: !=:
reference = {'Container': '1.0-e12affbba5f8a748882a3ae98aced282'} reference = {'Container': '1.0-e12affbba5f8a748882a3ae98aced282'}
actual = {'Container': '1.1-22b40e8eed0414561ca921906b189820'} actual = {'Container': '1.1-22b40e8eed0414561ca921906b189820'}
: Fields or remotable methods in some objects have changed. Make sure the versions of the objects has been bumped, and update the hashes in the static fingerprints tree (object_data). For more information, read http://docs.openstack.org/developer/magnum/objects.html. : Fields or remotable methods in some objects have changed. Make sure the versions of the objects has been bumped, and update the hashes in the static fingerprints tree (object_data). For more information, read http://docs.openstack.org/developer/magnum/objects.html.
I can now copy the new fingerprint needed (1.1-22b40e8eed0414561ca921906b189820), I can now copy the new fingerprint needed
to the object_data map within magnum/tests/unit/objects/test_objects.py:: (1.1-22b40e8eed0414561ca921906b189820), to the object_data map within
magnum/tests/unit/objects/test_objects.py::
object_data = { object_data = {
'Bay': '1.0-35edde13ad178e9419e7ea8b6d580bcd', 'Bay': '1.0-35edde13ad178e9419e7ea8b6d580bcd',

36
specs/container-networking-model.rst
View File

@ -179,7 +179,7 @@ Proposed Changes
flannel, weave, calico, midonet, netplugin, etc.. flannel, weave, calico, midonet, netplugin, etc..
Here is an example of creating a baymodel that uses Flannel as the Here is an example of creating a baymodel that uses Flannel as the
Libnetwork driver: Libnetwork driver: ::
magnum baymodel-create --name k8sbaymodel \ magnum baymodel-create --name k8sbaymodel \
--image-id fedora-21-atomic-3 \ --image-id fedora-21-atomic-3 \
@ -205,7 +205,7 @@ Proposed Changes
named "labels" for supplying driver-specific configuration parameters. named "labels" for supplying driver-specific configuration parameters.
Labels consist of one or more arbitrary key/value pairs. Here is an Labels consist of one or more arbitrary key/value pairs. Here is an
example of using labels to change default settings of the Flannel example of using labels to change default settings of the Flannel
Libnetwork driver: Libnetwork driver: ::
magnum baymodel-create --name k8sbaymodel \ magnum baymodel-create --name k8sbaymodel \
--image-id fedora-21-atomic-3 \ --image-id fedora-21-atomic-3 \
@ -307,29 +307,29 @@ Data Model Impact
This document adds the labels and libnetwork-driver attribute to the baymodel This document adds the labels and libnetwork-driver attribute to the baymodel
database table. A migration script will be provided to support the attribute database table. A migration script will be provided to support the attribute
being added. being added. ::
+-------------------+-----------------+---------------------------------------------+ +-------------------+-----------------+---------------------------------------------+
| Attribute | Type | Description | | Attribute | Type | Description |
+===================+=================+=============================================+ +===================+=================+=============================================+
| labels | JSONEncodedDict | One or more arbitrary key/value pairs | | labels | JSONEncodedDict | One or more arbitrary key/value pairs |
+-------------------+-----------------+---------------------------------------------+ +-------------------+-----------------+---------------------------------------------+
| libnetwork-driver | string | Container networking backend implementation | | libnetwork-driver | string | Container networking backend implementation |
+-------------------+-----------------+---------------------------------------------+ +-------------------+-----------------+---------------------------------------------+
REST API Impact REST API Impact
--------------- ---------------
This document adds the labels and libnetwork-driver attribute to the BayModel This document adds the labels and libnetwork-driver attribute to the BayModel
API class. API class. ::
+-------------------+-----------------+---------------------------------------------+ +-------------------+-----------------+---------------------------------------------+
| Attribute | Type | Description | | Attribute | Type | Description |
+===================+=================+=============================================+ +===================+=================+=============================================+
| labels | JSONEncodedDict | One or more arbitrary key/value pairs | | labels | JSONEncodedDict | One or more arbitrary key/value pairs |
+-------------------+-----------------+---------------------------------------------+ +-------------------+-----------------+---------------------------------------------+
| libnetwork-driver | string | Container networking backend implementation | | libnetwork-driver | string | Container networking backend implementation |
+-------------------+-----------------+---------------------------------------------+ +-------------------+-----------------+---------------------------------------------+
Security Impact Security Impact
--------------- ---------------

26
specs/magnum-horizon-plugin.rst
View File

@ -12,11 +12,11 @@ Launchpad blueprint:
https://blueprints.launchpad.net/magnum/+spec/magnum-horizon-plugin https://blueprints.launchpad.net/magnum/+spec/magnum-horizon-plugin
Currently there is no way for a user to interact with Magnum through a web based Currently there is no way for a user to interact with Magnum through a web
user interface, as they are used to doing with other OpenStack components. This based user interface, as they are used to doing with other OpenStack
implementation aims to introduce this interface as an extension of Horizon (the components. This implementation aims to introduce this interface as an
OpenStack Dashboard) and expose all the features of Magnum in a way familiar to extension of Horizon (the OpenStack Dashboard) and expose all the features of
users. Magnum in a way familiar to users.
Problem description Problem description
=================== ===================
@ -39,9 +39,9 @@ Use Cases
Proposed change Proposed change
=============== ===============
The first step will be to extend the Horizon API to include CRUD operations that The first step will be to extend the Horizon API to include CRUD operations
are needed to interact with Magnum. Assuming that there are no issues here and that are needed to interact with Magnum. Assuming that there are no issues here
API changes/additions are not required to Magnum, we can begin to and API changes/additions are not required to Magnum, we can begin to
design/implement the interface. We will aim to minimize the amount of Magnum design/implement the interface. We will aim to minimize the amount of Magnum
specific UI code that will need to be maintained by reusing components from specific UI code that will need to be maintained by reusing components from
Horizon. This will also speed up the development significantly. Horizon. This will also speed up the development significantly.
@ -50,11 +50,11 @@ It is suggested the initial implementation of Magnum UI will include basic CRUD
operations on BayModel and Bay resources. This will be the starting point for operations on BayModel and Bay resources. This will be the starting point for
development and upon completion this will represent version 1. development and upon completion this will represent version 1.
Future direction includes adding CRUD operations for other Magnum features (Pod, Future direction includes adding CRUD operations for other Magnum features
Container, Service, ReplicationController) and will be tracked by new blueprints (Pod, Container, Service, ReplicationController) and will be tracked by new
as they represent significant additional effort. The ultimate goal, a user blueprints as they represent significant additional effort. The ultimate goal,
should be able to perform all normal interactions with Magnum through the UI a user should be able to perform all normal interactions with Magnum through
with no need for interaction with the python client. the UI with no need for interaction with the python client.
Suggestions for further improvement include visualising Magnum resources to Suggestions for further improvement include visualising Magnum resources to
provide a quick overview of how resources are deployed. provide a quick overview of how resources are deployed.

1
test-requirements.txt
View File

@ -5,6 +5,7 @@
# Despite above warning added by global sync process, please use # Despite above warning added by global sync process, please use
# ascii betical order. # ascii betical order.
doc8 # Apache-2.0
coverage>=3.6 coverage>=3.6
fixtures>=1.3.1 fixtures>=1.3.1
hacking<0.11,>=0.10.0 # Apache-2.0 hacking<0.11,>=0.10.0 # Apache-2.0

4
tox.ini
View File

@ -38,7 +38,9 @@ commands = bandit -c bandit.yaml -r magnum -n5 -p magnum_conservative
commands = python setup.py testr --coverage --testr-args='{posargs}' commands = python setup.py testr --coverage --testr-args='{posargs}'
[testenv:docs] [testenv:docs]
commands = python setup.py build_sphinx commands =
doc8 -e .rst specs/ doc/source/ contrib/ CONTRIBUTING.rst HACKING.rst README.rst
python setup.py build_sphinx
[testenv:genconfig] [testenv:genconfig]
commands = commands =