From c3d8262ec54439a0e0d9b5aa4d0dbf58f284a436 Mon Sep 17 00:00:00 2001 From: Christian Berendt Date: Thu, 4 Aug 2016 15:09:10 +0200 Subject: [PATCH] Add doc8 test and improve rst syntax This will test all rst files inside the doc directory for style issues with doc8 (an opinionated style checker for rst styles of documentation). This will fix all syntax issues identified by doc8 and will improve the syntax. Change-Id: Id1b9563e07e77e306aef5a0767c98c27f87c5c0e --- doc/CONTRIBUTING.rst | 12 ++++++------ doc/advanced-configuration.rst | 23 ++++++++++++----------- doc/ceph-guide.rst | 12 ++++++------ doc/cinder-guide.rst | 2 +- doc/external-ceph-guide.rst | 8 +++++--- doc/heat-dev-env.rst | 12 +++++++----- doc/image-building.rst | 27 +++++++++++++++------------ doc/kibana-guide.rst | 17 +++++++++-------- doc/multinode.rst | 8 ++++---- doc/operating-kolla.rst | 6 +++--- doc/quickstart.rst | 30 ++++++++++++++++-------------- doc/security.rst | 2 +- doc/vagrant-dev-env.rst | 4 ++-- test-requirements.txt | 1 + tox.ini | 4 +++- 15 files changed, 91 insertions(+), 77 deletions(-) diff --git a/doc/CONTRIBUTING.rst b/doc/CONTRIBUTING.rst index dadc4b82f1..e6ec7a7fe7 100644 --- a/doc/CONTRIBUTING.rst +++ b/doc/CONTRIBUTING.rst @@ -7,16 +7,16 @@ How To Contribute Basics ====== -#. Our source code is hosted on `OpenStack GitHub`_, but pull requests submitted - through GitHub will be ignored. Bugs should be filed on launchpad_, - not GitHub. +#. Our source code is hosted on `OpenStack GitHub`_, but pull requests + submitted through GitHub will be ignored. Bugs should be filed on + launchpad_, not GitHub. #. Please follow OpenStack `Gerrit Workflow`_ to to contribute to Kolla. #. Note the branch you're proposing changes to. ``master`` is the current focus of development. Kolla project has a strict policy of only allowing backports - in ``stable/branch``, unless when not applicable. A bug in a ``stable/branch`` - will first have to be fixed in ``master``. + in ``stable/branch``, unless when not applicable. A bug in a + ``stable/branch`` will first have to be fixed in ``master``. #. Please file a launchpad_ blueprint for any significant code change and a bug for any significant bug fix or add a TrivialFix tag for simple changes. @@ -33,6 +33,6 @@ Development Environment ======================= #. Please follow our `quickstart`_ to deploy your environment and test your - changes. + changes. .. _quickstart: http://docs.openstack.org/developer/kolla/quickstart.html diff --git a/doc/advanced-configuration.rst b/doc/advanced-configuration.rst index 9ba0f0d318..ff393c1be0 100644 --- a/doc/advanced-configuration.rst +++ b/doc/advanced-configuration.rst @@ -67,7 +67,7 @@ TLS protection for the external VIP. TLS allows a client to authenticate the OpenStack service endpoint and allows for encryption of the requests and responses. -.. NOTE:: The kolla_internal_vip_address and kolla_external_vip_address must +.. note:: The kolla_internal_vip_address and kolla_external_vip_address must be different to enable TLS on the external network. The configuration variables that control TLS networking are: @@ -83,7 +83,7 @@ The default for TLS is disabled; to enable TLS networking: kolla_external_fqdn_cert: "{{ node_config_directory }}/certificates/mycert.pem" -.. NOTE:: TLS authentication is based on certificates that have been +.. note:: TLS authentication is based on certificates that have been signed by trusted Certificate Authorities. Examples of commercial CAs are Comodo, Symantec, GoDaddy, and GlobalSign. Letsencrypt.org is a CA that will provide trusted certificates at no charge. Many @@ -119,7 +119,7 @@ have settings similar to this: Self-Signed Certificates ======================== -.. NOTE:: Self-signed certificates should never be used in production. +.. note:: Self-signed certificates should never be used in production. It is not always practical to get a certificate signed by a well-known trust CA, for example a development or internal test kolla deployment. In @@ -144,18 +144,19 @@ TODO(all) fill this section out OpenStack Service Configuration in Kolla ======================================== -.. NOTE:: As of now kolla only supports config overrides for ini based configs. -An operator can change the location where custom config files are read from by -editing ``/etc/kolla/globals.yml`` and adding the following line. +.. note:: As of now kolla only supports config overrides for ini based configs. + An operator can change the location where custom config files are read + from by editing ``/etc/kolla/globals.yml`` and adding the following + line. :: # The directory to merge custom config files the kolla's config files node_custom_config: "/etc/kolla/config" -Kolla allows the operator to override configuration of services. Kolla will look -for a file in ``/etc/kolla/config/<< sevice name >>/<< config file >>``. This -can be done per-project, per-service or per-service-on-specified-host. +Kolla allows the operator to override configuration of services. Kolla will +look for a file in ``/etc/kolla/config/<< sevice name >>/<< config file >>``. +This can be done per-project, per-service or per-service-on-specified-host. For example to override scheduler_max_attempts in nova scheduler, the operator needs to create ``/etc/kolla/config/nova/nova-scheduler.conf`` with content: @@ -173,8 +174,8 @@ on host myhost, the operator needs to create file [DEFAULT] ram_allocation_ratio = 5.0 -The operator can make these changes after services were already deployed by using -following command: +The operator can make these changes after services were already deployed by +using following command: :: diff --git a/doc/ceph-guide.rst b/doc/ceph-guide.rst index 8a88f78b94..4f8afb3dc2 100644 --- a/doc/ceph-guide.rst +++ b/doc/ceph-guide.rst @@ -74,8 +74,8 @@ RGW requires a healthy cluster in order to be successfully deployed. On initial start up, RGW will create several pools. The first pool should be in an operational state to proceed with the second one, and so on. So, in the case of an **all-in-one** deployment, it is necessary to change the default number of -copies for the pools before deployment. Modify the file ``/etc/kolla/config/ceph.conf`` -and add the contents:: +copies for the pools before deployment. Modify the file +``/etc/kolla/config/ceph.conf`` and add the contents:: [global] osd pool default size = 1 @@ -129,8 +129,8 @@ must make the choice to use an erasure coded pool or a replicated pool (the default) when you initially deploy. You cannot change this without completely removing the pool and recreating it. -To enable erasure coded pools add the following options to your ``/etc/kolla/globals.yml`` -configuration file: +To enable erasure coded pools add the following options to your +``/etc/kolla/globals.yml`` configuration file: :: @@ -189,8 +189,8 @@ The default pool Ceph creates is named **rbd**. It is safe to remove this pool: Troubleshooting =============== -Deploy fails during 'Fetching Ceph keyrings ... No JSON object could be decoded' --------------------------------------------------------------------------------- +Deploy fails with 'Fetching Ceph keyrings ... No JSON object could be decoded' +------------------------------------------------------------------------------ If an initial deploy of Ceph fails, perhaps due to improper configuration or similar, the cluster will be partially formed and will need to be reset for a diff --git a/doc/cinder-guide.rst b/doc/cinder-guide.rst index 47c12b04b0..1c3f5a3a0f 100644 --- a/doc/cinder-guide.rst +++ b/doc/cinder-guide.rst @@ -25,7 +25,7 @@ a real physical volume or a loopback mounted file for development. present is via a Ceph deployment. If community members disagree with this decision, please report the specific use case in the Cinder bug tracker here: - `_bug 1571211 `__. + `_bug 1571211 `__. Create a Volume Group diff --git a/doc/external-ceph-guide.rst b/doc/external-ceph-guide.rst index fcd1bdbabf..105a089ccc 100644 --- a/doc/external-ceph-guide.rst +++ b/doc/external-ceph-guide.rst @@ -14,7 +14,7 @@ Requirements * An existing installation of Ceph * Existing Ceph storage pools * Existing credentials in Ceph for OpenStack services to connect to Ceph -(Glance, Cinder, Nova) + (Glance, Cinder, Nova) Enabling External Ceph ====================== @@ -166,7 +166,9 @@ Put ceph.conf and keyring file into ``/etc/kolla/config/nova``: $ ls /etc/kolla/config/nova ceph.client.nova.keyring ceph.conf -Configure nova-compute to use Ceph as the ephemeral backend by creating ``/etc/kolla/config/nova/nova-compute.conf`` and adding the following contents: +Configure nova-compute to use Ceph as the ephemeral backend by creating +``/etc/kolla/config/nova/nova-compute.conf`` and adding the following +contents: :: @@ -176,4 +178,4 @@ Configure nova-compute to use Ceph as the ephemeral backend by creating ``/etc/k images_rbd_ceph_conf=/etc/ceph/ceph.conf rbd_user=nova -NOTE: rbd_user might vary depending on your environment. +.. note:: ``rbd_user`` might vary depending on your environment. diff --git a/doc/heat-dev-env.rst b/doc/heat-dev-env.rst index 4b320b88a8..46e7d5813e 100644 --- a/doc/heat-dev-env.rst +++ b/doc/heat-dev-env.rst @@ -89,12 +89,14 @@ The container\_external\_subnet\_id: is the subnet equivalent to container\_external\_network\_id Review the parameters section of kollacluster.yaml for a full list of -configuration options. **Note:** You must provide values for: +configuration options. -- ``ssh_key_name`` -- ``external_network_id`` -- ``container_external_network_id`` -- ``container_external_subnet_id`` +.. note:: You must provide values for: + + - ``ssh_key_name`` + - ``external_network_id`` + - ``container_external_network_id`` + - ``container_external_subnet_id`` And then create the stack, referencing that environment file: diff --git a/doc/image-building.rst b/doc/image-building.rst index cdafffdfaa..76eb2e765c 100644 --- a/doc/image-building.rst +++ b/doc/image-building.rst @@ -19,6 +19,7 @@ Install tox and generate the build configuration. The build configuration is designed to hold advanced customizations when building containers. Create kolla-build.conf using the following steps. + :: pip install tox @@ -59,7 +60,7 @@ command line:: kolla-build keystone In this case, the build script builds all images which name contains the -*keystone* string along with their dependencies. +``keystone`` string along with their dependencies. Multiple names may be specified on the command line:: @@ -85,7 +86,7 @@ command:: tox -e genconfig -Build OpenStack from Source +Build OpenStack from source =========================== When building images, there are two methods of the OpenStack install. One is @@ -112,7 +113,7 @@ the best use of the docker cache. [keystone] type = git location = https://github.com/openstack/keystone - reference = stable/kilo + reference = stable/mitaka [heat-base] type = local @@ -122,11 +123,13 @@ the best use of the docker cache. type = local location = /tmp/ironic.tar.gz -To build RHEL containers, it is necessary to use the -i (include header) +To build RHEL containers, it is necessary to use the ``-i`` (include header) feature to include registration with RHN of the container runtime operating system. To obtain a RHN username/password/pool id, contact Red Hat. -First create a file called rhel-include:: +First create a file called ``rhel-include``: + +:: RUN subscription-manager register --user= --password= \ && subscription-manager attach --pool @@ -140,13 +143,13 @@ Custom Repos The build method allows the operator to build containers from custom repos. The repos are accepted as a list of comma separated values and can be in -the form of .repo, .rpm, or a url. See examples below. +the form of ``.repo``, ``.rpm,`` or a URL. See examples below. -Update rpm_setup_config in ``/etc/kolla/kolla-build.conf``:: +Update ``rpm_setup_config`` in ``/etc/kolla/kolla-build.conf``:: rpm_setup_config = http://trunk.rdoproject.org/centos7/currrent/delorean.repo,http://trunk.rdoproject.org/centos7/delorean-deps.repo -If specifying a .repo file, each .repo file will need to exist in the +If specifying a ``.repo`` file, each ``.repo`` file will need to exist in the same directory as the base Dockerfile (kolla/docker/base):: rpm_setup_config = epel.repo,delorean.repo,delorean-deps.repo @@ -187,7 +190,7 @@ image, the operator would add the following block to Known issues ============ -1. Can't build base image because docker fails to install systemd or httpd. +#. Can't build base image because docker fails to install systemd or httpd. There are some issues between docker and AUFS. The simple workaround to avoid the issue is that add ``-s devicemapper`` or ``-s btrfs`` to @@ -195,7 +198,7 @@ Known issues tracker `_ and `how to configure Docker with BTRFS backend `_. -2. Mirrors are unreliable. +#. Mirrors are unreliable. Some of the mirrors Kolla uses can be unreliable. As a result occasionally some containers fail to build. To rectify build problems, the build tool @@ -220,8 +223,8 @@ Running Docker registry is easy. Just use the following command:: docker run -d -p 4000:5000 --restart=always --name registry \ -v :/var/lib/registry registry -Note: ```` points to the folder where Docker registry -will store Docker images on the local host. +.. note:: ```` points to the folder where Docker registry + will store Docker images on the local host. The default port of Docker registry is 5000. But the 5000 port is also the port of keystone-api. To avoid conflict, use 4000 port as Docker registry port. diff --git a/doc/kibana-guide.rst b/doc/kibana-guide.rst index 1691373e14..787dfe22ca 100644 --- a/doc/kibana-guide.rst +++ b/doc/kibana-guide.rst @@ -31,8 +31,9 @@ following configuration: #. Time-field name - Timestamp After setting parameters, one can create an index with *Create* button. -Note: This step is necessary until the default Kibana dashboard is implemented -in Kolla. + +.. note:: This step is necessary until the default Kibana dashboard is implemented + in Kolla. Search logs - Discover tab ========================== @@ -63,9 +64,9 @@ generated and previewed. In the menu on the left, metrics for a chart can be chosen. The chart can be generated by pressing a green arrow on the top of the left-side menu. -NOTE: After creating a visualization, it can be saved by choosing *save -visualization* option in the menu on the right. If it is not saved, it will -be lost after leaving a page or creating another visualization. +.. note:: After creating a visualization, it can be saved by choosing *save + visualization* option in the menu on the right. If it is not saved, it + will be lost after leaving a page or creating another visualization. Organize visualizations and searches - Dashboard tab ==================================================== @@ -77,9 +78,9 @@ from all saved ones. The order and size of elements can be changed directly in this place by moving them or resizing. The color of charts can also be changed by checking a colorful dots on the legend near each visualization. -NOTE: After creating a dashboard, it can be saved by choosing *save dashboard* -option in the menu on the right. If it is not saved, it will be lost after -leaving a page or creating another dashboard. +.. note:: After creating a dashboard, it can be saved by choosing *save dashboard* + option in the menu on the right. If it is not saved, it will be lost after + leaving a page or creating another dashboard. If a Dashboard has already been saved, it can be opened by choosing *open dashboard* option in the menu on the right. diff --git a/doc/multinode.rst b/doc/multinode.rst index 80f52e00a8..b867cc1f08 100644 --- a/doc/multinode.rst +++ b/doc/multinode.rst @@ -24,8 +24,8 @@ with version greater than 2.3, do the following: docker run -d -p 4000:5000 --restart=always --name registry registry:2 -Note: Kolla looks for the Docker registry to use port 4000. (Docker default is -port 5000) +.. note:: Kolla looks for the Docker registry to use port 4000. (Docker default is + port 5000) After starting the registry, it is necessary to instruct Docker that it will be communicating with an insecure registry. To enable insecure registry @@ -52,7 +52,7 @@ Edit ``/etc/default/docker`` and add: # Ubuntu DOCKER_OPTS="--insecure-registry 192.168.1.100:4000" -If ubuntu is using systemd, additional settings needs to be configured. +If ubuntu is using systemd, additional settings needs to be configured. Copy docker's systemd unit file to ``/etc/systemd/system/`` directory: :: @@ -60,7 +60,7 @@ Copy docker's systemd unit file to ``/etc/systemd/system/`` directory: # cp /lib/systemd/system/docker.service /etc/systemd/system/docker.service Next, modify ``/etc/systemd/system/docker.service``, add ``environmentFile`` -variable and add ``$DOCKER_OPTS`` to the end of ExecStart in ``[Service]`` +variable and add ``$DOCKER_OPTS`` to the end of ExecStart in ``[Service]`` section: :: diff --git a/doc/operating-kolla.rst b/doc/operating-kolla.rst index ca30bcbea9..1ba05d0f4e 100644 --- a/doc/operating-kolla.rst +++ b/doc/operating-kolla.rst @@ -49,16 +49,16 @@ Then run the command to upgrade:: kolla-ansible upgrade -.. NOTE:: Varying degrees of success have been reported with upgrading +.. note:: Varying degrees of success have been reported with upgrading the libvirt container with a running virtual machine in it. The libvirt upgrade still needs a bit more validation, but the Kolla community feels confident this mechanism can be used with the correct Docker graph driver. -.. NOTE:: The Kolla community recommends the btrfs or aufs graph drivers for +.. note:: The Kolla community recommends the btrfs or aufs graph drivers for storing data as sometimes the LVM graph driver loses track of its reference counting and results in an unremovable container. -.. NOTE:: Because of system technical limitations, upgrade of a libvirt +.. note:: Because of system technical limitations, upgrade of a libvirt container when using software emulation (``virt_driver=qemu`` in nova.conf), does not work at all. This is acceptable because KVM is the recommended virtualization driver to use with Nova. diff --git a/doc/quickstart.rst b/doc/quickstart.rst index ae82b48bf4..c755dfa12e 100644 --- a/doc/quickstart.rst +++ b/doc/quickstart.rst @@ -16,7 +16,7 @@ The recommended deployment target requirements: - At least 8gb main memory - At least 40gb disk space. -.. NOTE:: Some commands below may require root permissions (e.g. pip, apt-get). +.. note:: Some commands below may require root permissions (e.g. pip, apt-get). Recommended Environment ======================= @@ -24,7 +24,8 @@ Recommended Environment If developing or evaluating Kolla, the community strongly recommends using bare metal or a virtual machine. Follow the instructions in this document to get started with deploying OpenStack on bare metal or a virtual machine with Kolla. -There are other deployment environments referenced below in `Additional Environments`_. +There are other deployment environments referenced below in +`Additional Environments`_. Install Dependencies ==================== @@ -48,7 +49,7 @@ and OverlayFS. In order to update kernel in Ubuntu 14.04 LTS to 4.2, run: apt-get -y install linux-image-generic-lts-wily -.. NOTE:: Install is *very* sensitive about version of components. Please +.. note:: Install is *very* sensitive about version of components. Please review carefully because default Operating System repos are likely out of date. @@ -61,7 +62,8 @@ Docker Python 1.6.0 none On target nodes Python Jinja2 2.8.0 none On deployment host ===================== =========== =========== ========================= -Make sure the ``pip`` package manager is installed and upgraded to latest before proceeding: +Make sure the ``pip`` package manager is installed and upgraded to latest +before proceeding: :: @@ -124,17 +126,17 @@ For Ubuntu 14.04 which uses upstart instead of systemd, run the following: mount --make-shared /run -.. NOTE:: If centos/fedora/oraclelinux container images are built on an Ubuntu +.. note:: If centos/fedora/oraclelinux container images are built on an Ubuntu host, the backend storage driver must not be AUFS (see the known issues in :doc:`image-building`). -.. NOTE:: On ubuntu 16.04, please uninstall ``lxd`` and ``lxc`` packages. (issue +.. note:: On ubuntu 16.04, please uninstall ``lxd`` and ``lxc`` packages. (issue with cgroup mounts, mounts exponentially increasing when restarting container). On the target hosts you also need an updated version of the Docker python libraries: -.. NOTE:: The old docker-python is obsoleted by python-docker-py. +.. note:: The old docker-python is obsoleted by python-docker-py. :: @@ -402,8 +404,8 @@ deployment. Optionally, the passwords may be populate in the file by hand. Start by editing ``/etc/kolla/globals.yml``. Check and edit, if needed, these parameters: ``kolla_base_distro``, ``kolla_install_type``. These parameters should match what you used in the ``kolla-build`` command line. The default for -``kolla_base_distro`` is ``centos`` and for ``kolla_install_type`` is ``binary``. -If you want to use ubuntu with source type, then you should make +``kolla_base_distro`` is ``centos`` and for ``kolla_install_type`` is +``binary``. If you want to use ubuntu with source type, then you should make sure ``globals.yml`` has the following entries: :: @@ -479,7 +481,7 @@ In order to see all available parameters, run: kolla-ansible -h -.. NOTE:: In case of deploying using the _nested_ environment (*eg*. +.. note:: In case of deploying using the _nested_ environment (*eg*. Using Virtualbox VM's, KVM VM's), if your compute node supports hardware acceleration for virtual machines. @@ -626,10 +628,10 @@ The values ````, ```` values are overridden, in ``/etc/kolla/globals.yml``. The value of ```` can be found in ``/etc/kolla/passwords.yml``. -Note: When you log in to Kibana web interface for the first time, you are -prompted to create an index. Please create an index using the name ``log-*``. -This step is necessary until the default Kibana dashboard is implemented in -Kolla. +.. note:: When you log in to Kibana web interface for the first time, you are + prompted to create an index. Please create an index using the name ``log-*``. + This step is necessary until the default Kibana dashboard is implemented in + Kolla. .. _Docker Hub Image Registry: https://hub.docker.com/u/kolla/ .. _launchpad bug: https://bugs.launchpad.net/kolla/+filebug diff --git a/doc/security.rst b/doc/security.rst index 4780df2ce6..f14dabaeb5 100644 --- a/doc/security.rst +++ b/doc/security.rst @@ -34,7 +34,7 @@ Another solution to the persistent data issue is to use a host bind mount which involves making, for sake of example, host directory ``var/lib/mysql`` available inside the container at ``var/lib/mysql``. This absolutely solves the problem of persistent data, but it introduces another security issue, -permissions. With this host bind mount solution the data in ``var/lib/mysql`` +permissions. With this host bind mount solution the data in ``var/lib/mysql`` will be owned by the mysql user in the container. Unfortunately, that mysql user in the container could have any UID/GID and thats who will own the data outside the container introducing a potential security risk. Additionally, this diff --git a/doc/vagrant-dev-env.rst b/doc/vagrant-dev-env.rst index f77b8b81f9..807b5d2658 100644 --- a/doc/vagrant-dev-env.rst +++ b/doc/vagrant-dev-env.rst @@ -47,8 +47,8 @@ On Ubuntu 14.04 it is as easy as:: sudo apt-get install vagrant ruby-dev ruby-libvirt python-libvirt libvirt-dev nfs-kernel-server -**Note:** Many distros ship outdated versions of Vagrant by default. When in -doubt, always install the latest from the downloads page above. +.. note:: Many distros ship outdated versions of Vagrant by default. When in + doubt, always install the latest from the downloads page above. Next install the hostmanager plugin so all hosts are recorded in ``/etc/hosts`` (inside each vm):: diff --git a/test-requirements.txt b/test-requirements.txt index 6955edd1f9..315b4f0671 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -3,6 +3,7 @@ # process, which may cause wedges in the gate later. bandit>=1.0.1 # Apache-2.0 bashate>=0.2 # Apache-2.0 +doc8 # Apache-2.0 hacking>=0.10.0 oslo.log>=1.14.0 # Apache-2.0 oslotest>=1.10.0 # Apache-2.0 diff --git a/tox.ini b/tox.ini index 3870dc9153..aabd118ae4 100644 --- a/tox.ini +++ b/tox.ini @@ -32,7 +32,9 @@ commands = bandit -r ansible/library dev docker kolla tests tools commands = {posargs} [testenv:docs] -commands = python setup.py build_sphinx +commands = + doc8 doc + python setup.py build_sphinx [testenv:setupenv] commands =