doc8 all documentation and fix doc style
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
parent
4381c685b3
commit
6bb1768847
@ -6,7 +6,7 @@ Magnum Style Commandments
|
||||
- Step 2: Read on
|
||||
|
||||
Magnum Specific Commandments
|
||||
---------------------------
|
||||
----------------------------
|
||||
|
||||
- [M301] policy.enforce_wsgi decorator must be the first decorator on a method.
|
||||
- [M322] Method's default argument shouldn't be mutable.
|
||||
|
||||
@ -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:
|
||||
|
||||
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.
|
||||
3. Definition Entry Point - Used to advertise the available template definitions.
|
||||
2. Template definition - Magnum's interface for interacting with the Heat
|
||||
template.
|
||||
3. Definition Entry Point - Used to advertise the available template
|
||||
definitions.
|
||||
|
||||
The Heat Template
|
||||
-----------------
|
||||
|
||||
The heat template is where most of the real work happens. The result of the Heat
|
||||
template should be a full Container Orchestration Environment.
|
||||
The heat template is where most of the real work happens. The result of the
|
||||
Heat template should be a full Container Orchestration Environment.
|
||||
|
||||
The Template Definition
|
||||
-----------------------
|
||||
|
||||
Template definitions are a mapping of Magnum object attributes and Heat template
|
||||
parameters, along with Magnum consumable template outputs. Each definition also
|
||||
denotes which Bay Types it can provide. Bay Types are how Magnum determines which
|
||||
of the enabled Template Definitions it will use for a given Bay.
|
||||
Template definitions are a mapping of Magnum object attributes and Heat
|
||||
template parameters, along with Magnum consumable template outputs. Each
|
||||
definition also denotes which Bay Types it can provide. Bay Types are how
|
||||
Magnum determines which of the enabled Template Definitions it will use for a
|
||||
given Bay.
|
||||
|
||||
The Definition Entry Point
|
||||
--------------------------
|
||||
|
||||
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`
|
||||
group. This example exposes it's Template Definition as `example_template = example_template:ExampleTemplate`
|
||||
in the `magnum.template_definitions` group.
|
||||
Each Template Definition should have an Entry Point in the
|
||||
`magnum.template_definitions` group. This example exposes it's Template
|
||||
Definition as `example_template = example_template:ExampleTemplate` in the
|
||||
`magnum.template_definitions` group.
|
||||
|
||||
Installing Bay Templates
|
||||
------------------------
|
||||
|
||||
Because Bay Templates are basically Python projects, they can be worked with like
|
||||
any other Python project. They can be cloned from version control and installed
|
||||
or uploaded to a package index and installed via utilities such as pip.
|
||||
Because Bay Templates are basically Python projects, they can be worked with
|
||||
like any other Python project. They can be cloned from version control and
|
||||
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
|
||||
`enabled_definitions` config option in magnum.conf.::
|
||||
|
||||
@ -33,6 +33,7 @@ Install OS-specific prerequisites::
|
||||
libmysqlclient-devel libopenssl-devel libxml2-devel \
|
||||
libxslt-devel postgresql-devel python-devel \
|
||||
gettext-runtime
|
||||
|
||||
Install pip::
|
||||
|
||||
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.
|
||||
|
||||
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::
|
||||
|
||||
|
||||
@ -18,12 +18,11 @@ Versioned Objects
|
||||
=================
|
||||
|
||||
Magnum uses the `oslo.versionedobjects library
|
||||
<http://docs.openstack.org/developer/oslo.versionedobjects/index.html>`_
|
||||
to construct an object model that
|
||||
can be communicated via RPC. These objects have a version history and
|
||||
functionality to convert from one version to a previous version. This allows for
|
||||
2 different levels of the code to still pass objects to each other, as in the
|
||||
case of rolling upgrades.
|
||||
<http://docs.openstack.org/developer/oslo.versionedobjects/index.html>`_ to
|
||||
construct an object model that can be communicated via RPC. These objects have
|
||||
a version history and functionality to convert from one version to a previous
|
||||
version. This allows for 2 different levels of the code to still pass objects
|
||||
to each other, as in the case of rolling upgrades.
|
||||
|
||||
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.fixture.ObjectVersionChecker
|
||||
<http://docs.openstack.org/developer/oslo.versionedobjects/api/fixture.html#oslo_versionedobjects.fixture.ObjectVersionChecker>`_
|
||||
generates fingerprints of
|
||||
each object, which is a combination of the current version number of the object,
|
||||
along with a hash of the RPC-critical parts of the object (fields and remotable
|
||||
methods).
|
||||
generates fingerprints of each object, which is a combination of the current
|
||||
version number of the object, along with a hash of the RPC-critical parts of
|
||||
the object (fields and remotable methods).
|
||||
|
||||
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
|
||||
@ -71,16 +69,17 @@ saying what I changed in the new version::
|
||||
# Version 1.1: Added 'foo' field
|
||||
VERSION = '1.1'
|
||||
|
||||
Now that I have updated the version, I will run the tests again and let the test
|
||||
tell me the fingerprint that I now need to put in the static tree::
|
||||
Now that I have updated the version, I will run the tests again and let the
|
||||
test tell me the fingerprint that I now need to put in the static tree::
|
||||
|
||||
testtools.matchers._impl.MismatchError: !=:
|
||||
reference = {'Container': '1.0-e12affbba5f8a748882a3ae98aced282'}
|
||||
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.
|
||||
|
||||
I can now copy the new fingerprint needed (1.1-22b40e8eed0414561ca921906b189820),
|
||||
to the object_data map within magnum/tests/unit/objects/test_objects.py::
|
||||
I can now copy the new fingerprint needed
|
||||
(1.1-22b40e8eed0414561ca921906b189820), to the object_data map within
|
||||
magnum/tests/unit/objects/test_objects.py::
|
||||
|
||||
object_data = {
|
||||
'Bay': '1.0-35edde13ad178e9419e7ea8b6d580bcd',
|
||||
|
||||
@ -179,7 +179,7 @@ Proposed Changes
|
||||
flannel, weave, calico, midonet, netplugin, etc..
|
||||
|
||||
Here is an example of creating a baymodel that uses Flannel as the
|
||||
Libnetwork driver:
|
||||
Libnetwork driver: ::
|
||||
|
||||
magnum baymodel-create --name k8sbaymodel \
|
||||
--image-id fedora-21-atomic-3 \
|
||||
@ -205,7 +205,7 @@ Proposed Changes
|
||||
named "labels" for supplying driver-specific configuration parameters.
|
||||
Labels consist of one or more arbitrary key/value pairs. Here is an
|
||||
example of using labels to change default settings of the Flannel
|
||||
Libnetwork driver:
|
||||
Libnetwork driver: ::
|
||||
|
||||
magnum baymodel-create --name k8sbaymodel \
|
||||
--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
|
||||
database table. A migration script will be provided to support the attribute
|
||||
being added.
|
||||
being added. ::
|
||||
|
||||
+-------------------+-----------------+---------------------------------------------+
|
||||
| Attribute | Type | Description |
|
||||
+===================+=================+=============================================+
|
||||
| labels | JSONEncodedDict | One or more arbitrary key/value pairs |
|
||||
+-------------------+-----------------+---------------------------------------------+
|
||||
| libnetwork-driver | string | Container networking backend implementation |
|
||||
+-------------------+-----------------+---------------------------------------------+
|
||||
+-------------------+-----------------+---------------------------------------------+
|
||||
| Attribute | Type | Description |
|
||||
+===================+=================+=============================================+
|
||||
| labels | JSONEncodedDict | One or more arbitrary key/value pairs |
|
||||
+-------------------+-----------------+---------------------------------------------+
|
||||
| libnetwork-driver | string | Container networking backend implementation |
|
||||
+-------------------+-----------------+---------------------------------------------+
|
||||
|
||||
REST API Impact
|
||||
---------------
|
||||
|
||||
This document adds the labels and libnetwork-driver attribute to the BayModel
|
||||
API class.
|
||||
API class. ::
|
||||
|
||||
+-------------------+-----------------+---------------------------------------------+
|
||||
| Attribute | Type | Description |
|
||||
+===================+=================+=============================================+
|
||||
| labels | JSONEncodedDict | One or more arbitrary key/value pairs |
|
||||
+-------------------+-----------------+---------------------------------------------+
|
||||
| libnetwork-driver | string | Container networking backend implementation |
|
||||
+-------------------+-----------------+---------------------------------------------+
|
||||
+-------------------+-----------------+---------------------------------------------+
|
||||
| Attribute | Type | Description |
|
||||
+===================+=================+=============================================+
|
||||
| labels | JSONEncodedDict | One or more arbitrary key/value pairs |
|
||||
+-------------------+-----------------+---------------------------------------------+
|
||||
| libnetwork-driver | string | Container networking backend implementation |
|
||||
+-------------------+-----------------+---------------------------------------------+
|
||||
|
||||
Security Impact
|
||||
---------------
|
||||
|
||||
@ -12,11 +12,11 @@ Launchpad blueprint:
|
||||
|
||||
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
|
||||
user interface, as they are used to doing with other OpenStack components. This
|
||||
implementation aims to introduce this interface as an extension of Horizon (the
|
||||
OpenStack Dashboard) and expose all the features of Magnum in a way familiar to
|
||||
users.
|
||||
Currently there is no way for a user to interact with Magnum through a web
|
||||
based user interface, as they are used to doing with other OpenStack
|
||||
components. This implementation aims to introduce this interface as an
|
||||
extension of Horizon (the OpenStack Dashboard) and expose all the features of
|
||||
Magnum in a way familiar to users.
|
||||
|
||||
Problem description
|
||||
===================
|
||||
@ -39,9 +39,9 @@ Use Cases
|
||||
Proposed change
|
||||
===============
|
||||
|
||||
The first step will be to extend the Horizon API to include CRUD operations that
|
||||
are needed to interact with Magnum. Assuming that there are no issues here and
|
||||
API changes/additions are not required to Magnum, we can begin to
|
||||
The first step will be to extend the Horizon API to include CRUD operations
|
||||
that are needed to interact with Magnum. Assuming that there are no issues here
|
||||
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
|
||||
specific UI code that will need to be maintained by reusing components from
|
||||
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
|
||||
development and upon completion this will represent version 1.
|
||||
|
||||
Future direction includes adding CRUD operations for other Magnum features (Pod,
|
||||
Container, Service, ReplicationController) and will be tracked by new blueprints
|
||||
as they represent significant additional effort. The ultimate goal, a user
|
||||
should be able to perform all normal interactions with Magnum through the UI
|
||||
with no need for interaction with the python client.
|
||||
Future direction includes adding CRUD operations for other Magnum features
|
||||
(Pod, Container, Service, ReplicationController) and will be tracked by new
|
||||
blueprints as they represent significant additional effort. The ultimate goal,
|
||||
a user should be able to perform all normal interactions with Magnum through
|
||||
the UI with no need for interaction with the python client.
|
||||
|
||||
Suggestions for further improvement include visualising Magnum resources to
|
||||
provide a quick overview of how resources are deployed.
|
||||
|
||||
@ -5,6 +5,7 @@
|
||||
# Despite above warning added by global sync process, please use
|
||||
# ascii betical order.
|
||||
|
||||
doc8 # Apache-2.0
|
||||
coverage>=3.6
|
||||
fixtures>=1.3.1
|
||||
hacking<0.11,>=0.10.0 # Apache-2.0
|
||||
|
||||
4
tox.ini
4
tox.ini
@ -38,7 +38,9 @@ commands = bandit -c bandit.yaml -r magnum -n5 -p magnum_conservative
|
||||
commands = python setup.py testr --coverage --testr-args='{posargs}'
|
||||
|
||||
[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]
|
||||
commands =
|
||||
|
||||
Loading…
Reference in New Issue
Block a user