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
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.

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:
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.::

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

@ -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::

27
doc/source/objects.rst
View File

@ -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',

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

@ -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,7 +307,7 @@ 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 |
@ -321,7 +321,7 @@ REST API Impact
---------------
This document adds the labels and libnetwork-driver attribute to the BayModel
API class.
API class. ::
+-------------------+-----------------+---------------------------------------------+
| Attribute | Type | Description |

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

@ -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.

1
test-requirements.txt
View File

@ -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
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}'
[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 =