From 6bb1768847f01ebf12b71e506ca744e59edbb3ad Mon Sep 17 00:00:00 2001 From: Tom Cammann Date: Wed, 16 Sep 2015 16:52:43 +0100 Subject: [PATCH] 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 --- HACKING.rst | 2 +- contrib/templates/example/README.rst | 33 ++++++++++++++----------- doc/source/dev/dev-quickstart.rst | 3 ++- doc/source/objects.rst | 27 ++++++++++----------- specs/container-networking-model.rst | 36 ++++++++++++++-------------- specs/magnum-horizon-plugin.rst | 26 ++++++++++---------- test-requirements.txt | 1 + tox.ini | 4 +++- 8 files changed, 70 insertions(+), 62 deletions(-) diff --git a/HACKING.rst b/HACKING.rst index f450b181da..4cd2ac5886 100644 --- a/HACKING.rst +++ b/HACKING.rst @@ -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. diff --git a/contrib/templates/example/README.rst b/contrib/templates/example/README.rst index 12e988d8a4..da30af85bc 100644 --- a/contrib/templates/example/README.rst +++ b/contrib/templates/example/README.rst @@ -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.:: diff --git a/doc/source/dev/dev-quickstart.rst b/doc/source/dev/dev-quickstart.rst index 349b5debb9..cd7731d318 100644 --- a/doc/source/dev/dev-quickstart.rst +++ b/doc/source/dev/dev-quickstart.rst @@ -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:: diff --git a/doc/source/objects.rst b/doc/source/objects.rst index 3a4a0673c1..4f0f764f51 100644 --- a/doc/source/objects.rst +++ b/doc/source/objects.rst @@ -18,12 +18,11 @@ Versioned Objects ================= Magnum uses the `oslo.versionedobjects library -`_ -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. +`_ 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 `_ -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', diff --git a/specs/container-networking-model.rst b/specs/container-networking-model.rst index bf62a6d5b1..b535ed5ed0 100644 --- a/specs/container-networking-model.rst +++ b/specs/container-networking-model.rst @@ -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 --------------- diff --git a/specs/magnum-horizon-plugin.rst b/specs/magnum-horizon-plugin.rst index 7183f7b01b..65bb3c2a7f 100644 --- a/specs/magnum-horizon-plugin.rst +++ b/specs/magnum-horizon-plugin.rst @@ -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. diff --git a/test-requirements.txt b/test-requirements.txt index 57abe6b78e..94baa0dc48 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -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 diff --git a/tox.ini b/tox.ini index 2aca904127..0ddbd83f17 100644 --- a/tox.ini +++ b/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 =