Enable doc8 linting

Keep our docs clean and try to avoid those cases where things are fine
until a sphinx or other dependency gets updated and suddenly starts
breaking.

Change-Id: I92e8ecd480937d55b968880c6c3d18885c3b12bf
Signed-off-by: Sean McGinnis <sean.mcginnis@gmail.com>

doc/requirements.txt

@@ -1,3 +1,4 @@
 pbr
 openstackdocstheme>=1.11.0 # Apache-2.0
 sphinx>=1.6.2 # BSD
+doc8>=0.6.0 # Apache-2.0

doc/source/dependency-management.rst

@@ -353,8 +353,8 @@ bot will generate an appropriate change itself. Ask in
 #openstack-infra if the bot needs to be run more quickly.
 
 Otherwise the change may be the result of recalculating the constraints which
-changed when a ``global-requirements.txt`` change is proposed. In this case, ignore
+changed when a ``global-requirements.txt`` change is proposed. In this case,
-the changes to ``upper-constraints.txt`` and review the
+ignore the changes to ``upper-constraints.txt`` and review the
 ``global-requirements.txt`` component of the change.
 
 stable-branch maintenance

doc/source/open-community.rst

@@ -151,9 +151,10 @@ of elected technical positions in OpenStack:
 
 The *project team* guide naturally focuses on PTLs. More information about the
 TC can be found on the `Technical Committee website`_. You can reach out to
-TC members using the openstack-discuss_ mailing-list (including the ``[tc]`` "tag"
+TC members using the openstack-discuss_ mailing-list (including the ``[tc]``
-in your subject line will make it more likely for them to see the message), or
+"tag" in your subject line will make it more likely for them to see the
-on the #openstack-tc IRC channel (especially around `TC office hours`_).
+message), or on the #openstack-tc IRC channel (especially around
+`TC office hours`_).
 
 Each project team in OpenStack needs a PTL. The PTL is an elected leader who
 has final say over all things in that specific project team, and all the code

doc/source/open-development.rst

@@ -55,7 +55,8 @@ guides them in the interaction with the contributor.
    recommend thing to do. Note that these project's guidelines inherit from the
    OpenStack's guidelines anyway.
 
-#. Verify that the commit message is also compliant with the following criterias:
+#. Verify that the commit message is also compliant with the following
+   criteria:
 
    #. The title is not longer than 50 characters.
    #. Summary lines should be wrapped at 70 characters.
@@ -64,11 +65,12 @@ guides them in the interaction with the contributor.
       Sometimes the patches are partially fixes for a bigger problem and
       it's extremely important to have all that explicitly stated in the
       commit message.
-   #. Make sure the commit message is correctly flagged. If there are API changes
+   #. Make sure the commit message is correctly flagged. If there are API
-      then the `APIImpact` flag should be used. If there are security
+      changes then the `APIImpact` flag should be used. If there are security
       implications then the `SecurityImpact` flag should be used. If there are
       documentation changes then the `DocImpact` flag should be used.
-   #. Make sure blueprints and bugs are correctly referenced in the commit message:
+   #. Make sure blueprints and bugs are correctly referenced in the commit
+      message:
 
       #. Closes-bug: #12345
       #. Implements-blueprint: my-blueprint-slug

doc/source/project-setup/javascript.rst

@@ -335,8 +335,8 @@ Suggested names patterns:
     A javascript library of common utilities used in other OpenStack
     projects, published to bower as :code:`openstack-oslo-jslib`
   :code:`openstack/ironic-jslib`
-    A javascript library that integrates with the Ironic API, published to bower
+    A javascript library that integrates with the Ironic API, published to
-    as :code:`openstack-ironic-jslib`
+    bower as :code:`openstack-ironic-jslib`
   :code:`openstack/ironic-jsclient`
     A commandline client for ironic, written in JavaScript, published to npm
     as :code:`openstack-ironic-jsclient`

doc/source/ptl.rst

@@ -136,7 +136,8 @@ At the beginning of a new cycle
 
 #.  Appoint `cross project liaisons`_ (Docs, release, QA, Oslo, etc.).
 
-#.  Appoint `FirstContact SIG liaisons`_ (By default, the liaison will be the PTL).
+#.  Appoint `First Contact SIG liaisons`_ (By default, the liaison will be the
+    PTL).
 
 #.  Check if the meeting time works for most active contributors.
 
@@ -145,7 +146,8 @@ At the beginning of a new cycle
 
 #.  If necessary, squash database migrations. This is usually not necessary,
     but will reduce the amount of time necessary for upgrading. A sample
-    squash can be seen `by the keystone team <https://github.com/openstack/keystone/commit/f5c64718a1c91fdce5c1da3b1043c14c5b0a97fd>`_.
+    squash can be seen `by the keystone
+    team <https://github.com/openstack/keystone/commit/f5c64718a1c91fdce5c1da3b1043c14c5b0a97fd>`_.
 
 #.  Track removed and deprecated features, for example using
     `deprecated-as-of-<series>` and `removed-as-of-<series>` blueprints.
@@ -170,9 +172,10 @@ During the cycle
 
 #.  Lack of reviews? Reach out to the core team and remind them.
 
-#.  `Release libraries as necessary <https://releases.openstack.org/reference/release_models.html#cycle-with-intermediary>`_,
+#.  `Release libraries as
-    but don't wait too long! Some teams will release after 4 weeks even if the changes are
+    necessary <https://releases.openstack.org/reference/release_models.html#cycle-with-intermediary>`_,
-    minor. *More often is better than less often.*
+    but don't wait too long! Some teams will release after 4 weeks even if the
+    changes are minor. *More often is better than less often.*
 
 Conference and event tasks
 ==========================
@@ -197,13 +200,14 @@ During the Forum
 #.  In the discussion sessions you moderate:
 
     * Take notes on the etherpad (or delegate a scribe)
-    * Act as a moderator rather than actively participate (or delegate a moderator)
+    * Act as a moderator rather than actively participate (or delegate a
+      moderator)
 
-#.  After the discussion, post a summary of the session outcome to the ML, for the
+#.  After the discussion, post a summary of the session outcome to the ML, for
-    benefit of those who could not be present.
+    the benefit of those who could not be present.
 
-#.  Towards the end of the Forum, ensure a summary of all discussions are sent to the ML for
+#.  Towards the end of the Forum, ensure a summary of all discussions are sent
-    individuals who did not attend the event.
+    to the ML for individuals who did not attend the event.
 
 Before the PTG
 --------------
@@ -215,8 +219,8 @@ Before the PTG
 #.  If your team gathers at the PTG, create an etherpad to dynamically build
     the room agenda, and list it on the event wiki page.
 
-#.  Create a tentative time schedule so that people from other projects who are interested
+#.  Create a tentative time schedule so that people from other projects who are
-    in a certain topic know when to join in the discussion.
+    interested in a certain topic know when to join in the discussion.
 
 During the PTG
 --------------
@@ -226,18 +230,19 @@ During the PTG
 #.  Keep the event schedule up to date on what the current topics of discussion
     in your team room is.
 
-#.  Towards the end of the PTG, ensure a summary of all discussions are sent to the ML for
+#.  Towards the end of the PTG, ensure a summary of all discussions are sent to
-    individuals who did not attend the event.
+    the ML for individuals who did not attend the event.
 
 Attending events
 ----------------
 
 Whilst attending the Summit and PTG as a PTL is preferential, it is not the
-end of the world if you are unable to do so for personal or professional reasons.
+end of the world if you are unable to do so for personal or professional
-The community is here to support you, and is available to help plan
+reasons. The community is here to support you, and is available to help plan
 team orientated events and tasks if you are unable to make the trip.
 
-If you are unable to attend, see our section on `How to successfully delegate`_.
+If you are unable to attend, see our section on
+`How to successfully delegate`_.
 
 At the end of the cycle
 =======================
@@ -245,8 +250,8 @@ At the end of the cycle
 #.  Clean up release notes.
 
 #.  Coordinate with the `release management`_ team for deliverables, unless a
-    liaison has been appointed and make sure release-highlights are documented in
+    liaison has been appointed and make sure release-highlights are documented
-    the release files.
+    in the release files.
 
 #.  Perform a retrospective via an etherpad. Suggested sections include:
     `What went well?`, `What didn't go well`.
@@ -360,7 +365,8 @@ some community tips on what you can do to help make your experience as an
 OpenStack project leader better.
 
 If you can think of anything else that might be helpful, do not hesitate
-to clone the `project-team-guide` repo from `OpenDev <https://opendev.org/openstack/project-team-guide>`_
+to clone the `project-team-guide` repo from
+`OpenDev <https://opendev.org/openstack/project-team-guide>`_
 and submit an addition.
 
 - Ensuring your email filters are setup to catch anything with `[ptl]` or
@@ -374,94 +380,97 @@ and submit an addition.
 - Project update emails: An optional extra for when you're getting into the
   swing of things. Providing an occasional project team update email to the
   openstack-discuss mailing list is a great way to keep part-time contributors
-  informed of the changes occurring within the project. For example, the Keystone
+  informed of the changes occurring within the project. For example, the
-  team provides updates weekly: http://lists.openstack.org/pipermail/openstack-discuss/2019-June/006799.html
+  Keystone team provides updates weekly:
+  http://lists.openstack.org/pipermail/openstack-discuss/2019-June/006799.html
 
-- Set aside time during the weekly meeting to look at the oldest outstanding review
+- Set aside time during the weekly meeting to look at the oldest outstanding
-  in the project. The resulting action should be one of the following: the patch is
+  review in the project. The resulting action should be one of the following:
-  merged, -1'd, or someone is assigned to follow up if the review cannot be completed
+  the patch is merged, -1'd, or someone is assigned to follow up if the review
-  in real time. This is a great way to reduce significant backlogs and potential
+  cannot be completed in real time. This is a great way to reduce significant
-  technical debt.
+  backlogs and potential technical debt.
 
 - Courtesy pings in IRC meetings: Everyone lives busy lives outside of the
   community. Coming up with a way to ping team members who are interested in
   attending team meetings is a helpful addition.
 
   Another way to do this is to encourage team members to configure their
-  IRC client to highlight on a specific keyword. For example `#startmeeting <PROJECT>`
+  IRC client to highlight on a specific keyword. For example
-  or `foo-team`.
+  `#startmeeting <PROJECT>` or `foo-team`.
 
-- Manage priority reviews. This can be done by adding a review priority column in Gerrit or
+- Manage priority reviews. This can be done by adding a review priority column
-  maintaining the priority `blueprint <https://blueprints.launchpad.net/>`_ in a spec repo.
+  in Gerrit or maintaining the priority
+  `blueprint <https://blueprints.launchpad.net/>`_ in a spec repo.
   Here is an example from the Cinder team implemented the review priority
   column: https://review.opendev.org/#/c/620664/
 
 How to successfully delegate
 ----------------------------
 
-Delegating is a large part of your role as an OpenStack PTL. There are numerous tasks
+Delegating is a large part of your role as an OpenStack PTL. There are numerous
-and we know how difficult it can be to keep up with it all. Some projects are more
+tasks and we know how difficult it can be to keep up with it all. Some projects
-fortunate than others, having multiple people around to delegate to, however this is
+are more fortunate than others, having multiple people around to delegate to,
-not always the case - no matter the size of the project.
+however this is not always the case - no matter the size of the project.
 
-The following are some tips and tricks derived from community members to help you
+The following are some tips and tricks derived from community members to help
-delegate:
+you delegate:
 
 - Reach out to team members on IRC or the mailing lists - everyone communicates
   differently.
 
-- Detail your ask. Vague requests tend to go ignored because people have their own
+- Detail your ask. Vague requests tend to go ignored because people have their
-  workloads. But if you need someone to host a team meeting, summarize the forum or
+  own workloads. But if you need someone to host a team meeting, summarize the
-  PTG, or even fix a bug, details are key to getting results.
+  forum or PTG, or even fix a bug, details are key to getting results.
 
-- Don't wait until the last minute to ask for help. If you've got a big project on
+- Don't wait until the last minute to ask for help. If you've got a big project
-  horizon, find someone to help at the beginning - even if that person is to be your
+  on horizon, find someone to help at the beginning - even if that person is to
-  backup if things fall through.
+  be your backup if things fall through.
 
 If you can't find a delegate, it is okay to let things go. It is not the upmost
-importance to have a team meeting, or plan everything perfectly. Here are some tips
+importance to have a team meeting, or plan everything perfectly. Here are some
-to help you deal with being unable to delegate tasks:
+tips to help you deal with being unable to delegate tasks:
 
-- Do not be afraid to reach out to other project teams, the TC, or the UC for help.
+- Do not be afraid to reach out to other project teams, the TC, or the UC for
-  The TC and the UC are designed to provide guidance and support where possible.
+  help. The TC and the UC are designed to provide guidance and support where
+  possible.
 
-- Don't be a hero. Ensure people are aware that you are having troubles and some deliverables
+- Don't be a hero. Ensure people are aware that you are having troubles and
-  might not be met. We care about our community members, and it's important that you feel
+  some deliverables might not be met. We care about our community members, and
-  supported, and not crushed.
+  it's important that you feel supported, and not crushed.
 
 Handing over PTL duties
 =======================
 
-Are you thinking of moving on? Hoping to encouraging healthy rotation in the role?
+Are you thinking of moving on? Hoping to encouraging healthy rotation in the
-Perhaps you've decided you've had enough and you're burnt out. Or perhaps you're
+role? Perhaps you've decided you've had enough and you're burnt out. Or perhaps
-moving to a new role or company and OpenStack is no longer your work priority.
+you're moving to a new role or company and OpenStack is no longer your work
-There are a myriad of reasons why someone would need or want to move on from
+priority. There are a myriad of reasons why someone would need or want to move
-the PTL position. While the community would be sad to see you step down, it is
+on from the PTL position. While the community would be sad to see you step
-part of the lifecycle of the position and it's often a positive change to see new
+down, it is part of the lifecycle of the position and it's often a positive
-people and new ideas into leadership positions.
+change to see new people and new ideas into leadership positions.
 
-Handing over the PTL position is not easy, it's not as simple as pinging someone
+Handing over the PTL position is not easy, it's not as simple as pinging
-who is an active contributor and asking if they're interested or not. The main thing
+someone who is an active contributor and asking if they're interested or not.
-is to get the individual up to speed on the content covered in this document, as it
+The main thing is to get the individual up to speed on the content covered in
-may be things they have not encountered yet.
+this document, as it may be things they have not encountered yet.
 
 .. note::
 
-   There are some important bits of information to pass on, but you're never going
+   There are some important bits of information to pass on, but you're never
-   to have a complete knowledge transfer. This is okay!
+   going to have a complete knowledge transfer. This is okay!
 
-To make that process a little bit easier for you, and for them, offer PTL mentoring
+To make that process a little bit easier for you, and for them, offer PTL
-before stepping down. If you know that your situation is going to change in advance,
+mentoring before stepping down. If you know that your situation is going to
-why not reach out to the whole team and ask who is interested and if you could mentor
+change in advance, why not reach out to the whole team and ask who is
-them in the last few months?
+interested and if you could mentor them in the last few months?
 
-If there are no takers, reach out to the OpenStack TC before stepping down so they
+If there are no takers, reach out to the OpenStack TC before stepping down so
-are aware of the current situation and can step in to help.
+they are aware of the current situation and can step in to help.
 
 .. _meetings: http://docs.openstack.org/project-team-guide/cross-project.html#meetings
 .. _release calendar: https://releases.openstack.org/schedule.ics
 .. _cross project liaisons: https://wiki.openstack.org/wiki/CrossProjectLiaisons
 .. _release management: http://docs.openstack.org/project-team-guide/release-management.html
-.. _FirstContact SIG liaisons: https://wiki.openstack.org/wiki/First_Contact_SIG#Project_Liaisons
+.. _First Contact SIG liaisons: https://wiki.openstack.org/wiki/First_Contact_SIG#Project_Liaisons
 .. _weekly meetings: http://eavesdrop.openstack.org/#User_Committee_Meeting
 .. _openstack-discuss: http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-discuss

doc/source/release-management.rst

@@ -741,9 +741,9 @@ You can check on the formatting of the output by either running locally:
 
   tox -e docs
 
-And checking the resulting file under ``doc/build/html/$RELEASE/highlights.html``,
+And checking the resulting file under
-or you can view the output of the ``build-openstack-sphinx-docs`` job under
+``doc/build/html/$RELEASE/highlights.html``, or you can view the output of the
-``html/$RELEASE/highlights.html``.
+``build-openstack-sphinx-docs`` job under ``html/$RELEASE/highlights.html``.
 
 Writing a Good Cycle Highlight
 ------------------------------

doc/source/stable-branches.rst

@@ -44,9 +44,9 @@ in the Maintained phase while all other projects have transitioned to either
 `Extended Maintenance`_ or even `End of Life`_.
 
 .. note::
-   At this time the exact mechanism for describing and updating this state is undefined
+   At this time the exact mechanism for describing and updating this state is
-   but it's probable it will involved updating a meta-data in a projects
+   undefined but it's probable it will involved updating a meta-data in a
-   deliverable file in the :code:`openstack/releases` repo.
+   projects deliverable file in the :code:`openstack/releases` repo.
 
 .. _Maintained:
 
@@ -72,8 +72,8 @@ releases and `OpenStack Vulnerability Management`_ will be reasonable efforts
 only.  There is no statement about the level of testing and upgrades from
 Extended Maintenance are not supported within the Community.
 
-The ``last release`` of the appropriate branch will be tagged as ``$series-em``,
+The ``last release`` of the appropriate branch will be tagged as
-for example: https://review.opendev.org/608296/.
+``$series-em``, for example: https://review.opendev.org/608296/.
 For all projects that follow the stable policy a patch with a ``$series-em``
 tag will be automatically generated after the final release from the latest
 development cycle happened. This is because this is a less busy period in
@@ -98,10 +98,11 @@ of Life`_ below.
 Unmaintained
 ------------
 
-At this stage of the project/branch the Extended Maintenance policy applies but CI
+At this stage of the project/branch the Extended Maintenance policy applies but
-may not be working and/or there aren't any active maintainers.  Projects that
+CI may not be working and/or there aren't any active maintainers.  Projects
-remain in this state for 6 months will be transitioned to `End of Life`_.
+that remain in this state for 6 months will be transitioned to `End of Life`_.
-Should  maintainers be found a project can be placed back into Extended Maintenance.
+Should  maintainers be found a project can be placed back into Extended
+Maintenance.
 
 .. _End Of Life:
 
@@ -214,20 +215,20 @@ branches which generally includes:
    appropriate branches quickly.
 #. Monitoring the backlog of open backport reviews and actually reviewing them
    in a timely manner.
-#. Releasing frequently enough to get fixes out without overwhelming the release
+#. Releasing frequently enough to get fixes out without overwhelming the
-   team or consumers. In general, security fixes and other critical bug fixes
+   release team or consumers. In general, security fixes and other critical bug
-   should be released quickly. Otherwise when there are a reasonable amount of
+   fixes should be released quickly. Otherwise when there are a reasonable
-   unreleased fixes committed, teams should be looking at doing a release.
+   amount of unreleased fixes committed, teams should be looking at doing a
-   Milestone boundaries during the master release schedule are also good times
+   release. Milestone boundaries during the master release schedule are also
-   to be inspecting the list of unreleased changes to see if a stable point
+   good times to be inspecting the list of unreleased changes to see if a
-   release should happen.
+   stable point release should happen.
 #. Monitoring and resolving issues in the continuous integration 'gate' system.
    This basically means making sure there aren't things blocking proposed
    backports from passing tests. These could be project-specific or global in
    nature and are usually tracked in the `stable tracker etherpad`_. From time
    to time the Stable Maintenance Core team may also ask for help from
-   individual projects in IRC or the openstack-discuss mailing list and expect a
+   individual projects in IRC or the openstack-discuss mailing list and expect
-   reasonably prompt response.
+   a reasonably prompt response.
 
    .. note::
       Projects with the ``stable:follows-policy`` tag should be running the
@@ -304,7 +305,8 @@ Backport examples:
 
 * A change for Tango must exist in :code:`master`
 * A change for Sierra must exist in :code:`stable/tango` and :code:`master`
-* A change for Romeo must exist in :code:`stable/sierra`, :code:`stable/tango` and :code:`master`
+* A change for Romeo must exist in :code:`stable/sierra`, :code:`stable/tango`
+  and :code:`master`
 * and so on
 
 Proposing Fixes
@@ -320,11 +322,11 @@ If you don't have the appropriate permissions to nominate the bug, then tagging
 it with e.g. *$release-backport-potential* is also sufficient e.g.
 `Nova Liberty potential`_
 
-The best way to get the patch merged in a timely manner is to send it backported
+The best way to get the patch merged in a timely manner is to send it
-by yourself. To do so, you may try to use the "Cherry Pick To" button in the
+backported by yourself. To do so, you may try to use the "Cherry Pick To"
-Gerrit UI for the original patch in master. Gerrit will take care of creating a
+button in the Gerrit UI for the original patch in master. Gerrit will take care
-new review, modifying the commit message to include 'cherry-picked from ...'
+of creating a new review, modifying the commit message to include
-line etc.
+'cherry-picked from ...' line etc.
 
 .. note::
    The backport must match the master commit, unless there is a serious need to
@@ -373,10 +375,10 @@ Email Notifications
 If you want to be notified of new stable patches you can create a watch on the
 gerrit `watched projects`_ screen with the following settings.
 
-.. code-block:: none
+.. code-block::
 
- Project Name: All-Projects
+   Project Name: All-Projects
-      Only If: branch:stable/liberty
+        Only If: branch:stable/liberty
 
 Then check the "Email Notifications - New Changes" checkbox. That will cause
 gerrit to send an email whenever a matching change is proposed, and better yet,

tox.ini

@@ -16,4 +16,10 @@ commands = {posargs}
 [testenv:docs]
 basepython = python3
 deps = -r{toxinidir}/doc/requirements.txt
-commands = sphinx-build -W -b html doc/source doc/build/html
+commands =
+    doc8
+    sphinx-build -W -b html doc/source doc/build/html
+
+[doc8]
+ignore-path=.tox,doc/build,.eggs/,./*.txt,project_team_guide.egg-info/
+extensions=.txt,.rst,.inc