diff --git a/doc/source/common/setup-gerrit.rst b/doc/source/common/setup-gerrit.rst index baf560a..e1d5c55 100644 --- a/doc/source/common/setup-gerrit.rst +++ b/doc/source/common/setup-gerrit.rst @@ -53,9 +53,9 @@ Individual Contributors ^^^^^^^^^^^^^^^^^^^^^^^ #. In Gerrit's `settings `_ - click the **New Contributor Agreement** link and sign the agreement. You need - this to contribute code & documentation. You will not be able to push patches - to Gerrit without this. + click the **New Contributor Agreement** link and sign the + agreement. You need this to contribute code & documentation. You + will not be able to push patches to Gerrit without this. .. image:: /_assets/account-setup/3.png :scale: 70% diff --git a/doc/source/common/task-tracking.rst b/doc/source/common/task-tracking.rst index 9d0863d..0d24210 100644 --- a/doc/source/common/task-tracking.rst +++ b/doc/source/common/task-tracking.rst @@ -40,10 +40,12 @@ project Z. Those changes need to merge in order to complete feature A. Boards & Worklists ------------------ -Worklists and Boards are different ways of organizing work. It is up to the project -team how stories are organized. They could be sorted by milestone. A lane could -have all the bugs or all the new features. It depends on the teams way of organizing -and coordinating work. Order of stories in a worklist could convey priority as well. + +Worklists and Boards are different ways of organizing work. It is up +to the project team how stories are organized. They could be sorted by +milestone. A lane could have all the bugs or all the new features. It +depends on the teams way of organizing and coordinating work. Order of +stories in a worklist could convey priority as well. Launchpad ========= @@ -60,27 +62,30 @@ or blueprints. Blueprints ---------- -In Launchpad, a new feature is called a blueprint. To file a new blueprint, click the -'Register a blueprint' button on the right. +In Launchpad, a new feature is called a blueprint. To file a new +blueprint, click the 'Register a blueprint' button on the right. -On the next screen you are prompted to add details including its name and title. +On the next screen you are prompted to add details including its name +and title. .. image:: /_assets/task_tracking/LP-overview.png :scale: 30 -These are different in that the name is what is used in the generated url and the -title is what displays when blueprints are listed out (name: new_ibm_driver -title: New IBM ISCSI Driver). The next most important part is the summary- a -description of the code change, where most of the details about the implementation -are. After that, there are several optional fields you may wish to fill in- a -specification url, assignee, drafter, and approver. The last two fields before -registering have default values- status and propose for a sprint. For most teams, -it is typical to leave the default values. +These are different in that the name is what is used in the generated +url and the title is what displays when blueprints are listed out +(name: new_ibm_driver title: New IBM ISCSI Driver). The next most +important part is the summary- a description of the code change, where +most of the details about the implementation are. After that, there +are several optional fields you may wish to fill in- a specification +url, assignee, drafter, and approver. The last two fields before +registering have default values- status and propose for a sprint. For +most teams, it is typical to leave the default values. -It is possible to update all of this information except the name and title after -the blueprint is registered. When you have finished filling out all of the -information you care to include, it is good to communicate with the project -team lead that you have filed a blueprint. +It is possible to update all of this information except the name and +title after the blueprint is registered. When you have finished +filling out all of the information you care to include, it is good to +communicate with the project team lead that you have filed a +blueprint. .. image:: /_assets/task_tracking/LP-bp.png :scale: 40 @@ -93,45 +98,50 @@ Bugs are pretty self explanitory- some unexpected or unintended behavior of the software. To report a bug you have found in Launchpad, click the 'Report a bug' button from the project's overview page. -To get to the details of reporting the bug you fill in the summary line and click -'next'. +To get to the details of reporting the bug you fill in the summary +line and click 'next'. .. image:: /_assets/task_tracking/LP-bug.png :scale: 40 -Based on the summary line, Launchpad will do a quick query to see if there has been -anything reported already that might be the same issue you are trying to report. -It is important to look through these to avoid filing duplicate bugs and creating -redundancies in the bug index. If you do not see a bug that sounds like the issue -you are reporting, you can click the 'No, I need to report a new bug' button. +Based on the summary line, Launchpad will do a quick query to see if +there has been anything reported already that might be the same issue +you are trying to report. It is important to look through these to +avoid filing duplicate bugs and creating redundancies in the bug +index. If you do not see a bug that sounds like the issue you are +reporting, you can click the 'No, I need to report a new bug' button. .. image:: /_assets/task_tracking/LP-bug-2.png :scale: 40 -After clicking that button, the further information field will appear along with the -'This bug is a security vulnerability' radio box. You can edit the summary line to -differentiate it from the other bugs Launchpad thought it was similar to, add details -like the setup you were using, what you were doing when you hit the unexpected -behavior, the error codes you encountered, etc. +After clicking that button, the further information field will appear +along with the 'This bug is a security vulnerability' radio box. You +can edit the summary line to differentiate it from the other bugs +Launchpad thought it was similar to, add details like the setup you +were using, what you were doing when you hit the unexpected behavior, +the error codes you encountered, etc. -If the bug is related to a security vulnerability it is important to click the box to -alert the Vulnerability Management Team to the issue. When you feel you have added -all of the information needed, go ahead and submit the bug report. For more information -about the full process for reporting security vulnerabilties, please continue reading -`this page `_. +If the bug is related to a security vulnerability it is important to +click the box to alert the Vulnerability Management Team to the issue. +When you feel you have added all of the information needed, go ahead +and submit the bug report. For more information about the full process +for reporting security vulnerabilties, please continue reading `this +page `_. .. image:: /_assets/task_tracking/LP-bug-3.png :scale: 30 -It is a good idea to check back on the bug routinely if you aren't actively working on -solving it to make sure people haven't asked for more information about the issue. If -someone has commented on the bug, try to respond with the details they need. +It is a good idea to check back on the bug routinely if you aren't +actively working on solving it to make sure people haven't asked for +more information about the issue. If someone has commented on the bug, +try to respond with the details they need. **Bug Status** -All bugs have a status lifecycle. They start as 'New' and move to other statuses from -there depending on what all is included in the description and if others can duplicate -the issue. Resolved statuses, meaning there is no more work to be done on the bug are: -'Fix Released', 'Invalid', or 'Won't Fix'. +All bugs have a status lifecycle. They start as 'New' and move to +other statuses from there depending on what all is included in the +description and if others can duplicate the issue. Resolved statuses, +meaning there is no more work to be done on the bug are: 'Fix +Released', 'Invalid', or 'Won't Fix'. .. list-table:: :widths: 20 100 diff --git a/test-requirements.txt b/test-requirements.txt index 7a5c9c5..271e7eb 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -4,3 +4,4 @@ sphinx>=1.6.2 # BSD openstackdocstheme>=1.11.0 # Apache-2.0 +doc8>=0.6.0 # Apache-2.0 diff --git a/tox.ini b/tox.ini index 951953b..5b0b7c8 100644 --- a/tox.ini +++ b/tox.ini @@ -1,12 +1,12 @@ [tox] minversion = 2.0 -envlist = checkbuild +envlist = docs,pep8 skipsdist = True [testenv] usedevelop = True setenv = VIRTUAL_ENV={envdir} -install_command = pip install -U {opts} {packages} +install_command = pip install {opts} {packages} deps = -r{toxinidir}/requirements.txt -r{toxinidir}/test-requirements.txt @@ -14,5 +14,8 @@ deps = [testenv:venv] commands = {posargs} +[testenv:pep8] +commands = doc8 doc + [testenv:docs] -commands = python setup.py build_sphinx +commands = sphinx-build -b html -W doc/source doc/build/html