Fix format errors in PTI docs

Extra spaces and unnecessary tags are causing sections to be block
quoted and other incorrect formatting in the rendered output.

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

reference/pti/golang.rst

@@ -14,13 +14,13 @@ and they follow OpenStack processes where feasible.
 
 Each golang project must be able to do:
 
- - Dependency installation
+- Dependency installation
- - Code style checks
+- Code style checks
- - Unit tests
+- Unit tests
- - Functional tests
+- Functional tests
- - Test Coverage Report
+- Test Coverage Report
- - Documentation generation
+- Documentation generation
- - Translations import/export and merge for translated projects
+- Translations import/export and merge for translated projects
 
 There is not yet a consensus among the to golang community for build
 and package management tools as the ``go`` tool itself was intended to
@@ -41,40 +41,40 @@ Specific commands
 To drive the above tasks, the following commands should be supported in
 a clean tree:
 
-    :code:`make depend`
+``make depend``
-        Install dependencies required to build the project
+    Install dependencies required to build the project
 
-    :code:`make build`
+``make build``
-        Execute build process
+    Execute build process
 
-    :code:`make install`
+``make install``
-        Execute binary install
+    Execute binary install
 
-    :code:`make test`
+``make test``
-        Execute tests
+    Execute tests
 
-    :code:`make fmt`
+``make fmt``
-        Execute code style checks
+    Execute code style checks
 
-    :code:`make docs`
+``make docs``
-        Generate HTML documentation from the in-tree developer docs
+    Generate HTML documentation from the in-tree developer docs
 
-    :code:`make godoc`
+``make godoc``
-        Generate the golang docs from the source
+    Generate the golang docs from the source
 
-    :code:`make releasenotes`
+``make releasenotes``
-        Generate HTML release notes
+    Generate HTML release notes
 
 Additional commands may be supported, but are not required:
 
-    :code:`make cover`
+``make cover``
-        Generate coverage reports
+    Generate coverage reports
 
-    :code:`make lint`
+``make lint``
-        Execute more code style checks
+    Execute more code style checks
 
-    :code:`make translation`
+``make translation``
-        Perform translation-related tasks (TBD)
+    Perform translation-related tasks (TBD)
 
 Project Setup
 -------------
@@ -82,24 +82,25 @@ Project Setup
 Project repos shall use a structure that is a hybrid of the typical OpenStack
 structure and those commonly found in the golang community.  Because
 these are OpenStack projects, the top-level structure shall contain
-the existing process-related components.  All golang source code and modules shall
+the existing process-related components.  All golang source code and modules
-be in one or more subdirectories named in a manner to identify its contents
+shall be in one or more subdirectories named in a manner to identify its
-distinctly from the Python namespace directories currently used.
+contents distinctly from the Python namespace directories currently used.
 This allows the golang code to maintain its native style and not be
 mixed in with the OpenStack tool-related pieces such as Sphinx documentation
 and Reno release notes.
 
 The source subdirectory naming is intentionally flexible in order to
 accommodate unforeseen situations, however the following guidelines should
-be strongly considered::
+be strongly considered:
 
- - Simple projects or projects that only need one golang workspace can use
+- Simple projects or projects that only need one golang workspace can use
-   a single top-level directory named ``go``.
+  a single top-level directory named ``go``.
- - Projects that may have multiple distinct golang workspaces should use
+
-   names that include a ``-go`` suffix.  This allows similarly named modules
+- Projects that may have multiple distinct golang workspaces should use
-   in multiple languages to co-exist. For example: the CloudTool project
+  names that include a ``-go`` suffix.  This allows similarly named modules
-   should continue to put Python sources in its Python namespace ``cloudtool``
+  in multiple languages to co-exist. For example: the CloudTool project
-   and the golang source in ``cloudtool-go`` (do not use a period!).
+  should continue to put Python sources in its Python namespace ``cloudtool``
+  and the golang source in ``cloudtool-go`` (do not use a period!).
 
 Dependency Management
 ---------------------
@@ -108,8 +109,8 @@ OpenStack has chosen to use Glide_ as the common dependency management tool
 for golang.  The ``depend`` target provides a common interface to Glide's
 ``install`` command.
 
-    :code:`make depend`
+``make depend``
-        Install dependencies required to build the project
+   Install dependencies required to build the project
 
 Golang dependencies shall not be vendored in golang repos. Each project shall
 include a list of its dependencies and acceptable/tested versions in the repo.
@@ -144,11 +145,11 @@ other operations such as ``go test``.  Build and install are split out here
 as they are common operations and useful in their own right.  These targets
 are not strictly necessary for CI testing.
 
-    :code:`make build`
+``make build``
-        Execute build process
+    Execute build process
 
-    :code:`make install`
+``make install``
-        Execute binary install
+    Execute binary install
 
 Codestyle Checks
 ----------------
@@ -159,12 +160,12 @@ target shall not use ``go fmt`` which rewrites source files by default.
 As a developer convenience a second target called ``fmtfix`` shall be
 defined that does the source fixups (equivalent to ``gofmt -l -w``).
 
-    :code:`make fmt`
+``make fmt``
-        Run the gofmt tool non-destructively to validate code formatting
+    Run the gofmt tool non-destructively to validate code formatting
 
-    :code:`make fmtfix`
+``make fmtfix``
-        Run the gofmt tool and overwrite source files with gofmt's version
+    Run the gofmt tool and overwrite source files with gofmt's version
-        if changes are required.  This is primarily a developer convenience.
+    if changes are required.  This is primarily a developer convenience.
 
 Tests
 -----
@@ -172,8 +173,8 @@ Tests
 OpenStack uses ``go test`` to run all test types at once invoked via
 the ``Makefile``.
 
-    :code:`make test`
+``make test``
-        Run tests
+    Run tests
 
 This is the general test target and may simply call some subset of additional
 ``test-*`` targets.  Specific test targets should be named with a ``test-*``
@@ -203,8 +204,8 @@ Sphinx to generate our Narrative Project documentation.
 In addition to the normal PTI :ref:`pti-documentation` requirements, for
 developer convenience, Go projects are recommended to provide:
 
-    :code:`make docs`
+``make docs``
-        Generate HTML documentation from the in-tree developer docs
+    Generate HTML documentation from the in-tree developer docs
 
 that should:
 
@@ -220,8 +221,8 @@ Go has a well-defined documentation tool `godoc`_ that produces
 developer documentation extracted from source code comments, similar to
 Python's Docstring.
 
-    :code:`make godoc`
+``make godoc``
-        Generate the golang docs from the source
+    Generate the golang docs from the source
 
 .. TBD(dtroyer): define how the godoc output is integrated with the current
 .. sphinx process
@@ -237,8 +238,8 @@ the final HTML documentation.
 In addition to the normal PTI :ref:`pti-documentation` requirements, for
 developer convenience, Go projects are recommended to provide:
 
-    :code:`make releasenotes`
+``make releasenotes``
-        Generate HTML release notes
+    Generate HTML release notes
 
 Translations
 ------------

reference/pti/javascript.rst

@@ -5,23 +5,23 @@ Project Testing Interface: JavaScript
 This document outlines common ways to meet the Project Testing Interface
 requirements for JavaScript. Each JavaScript project must be able to do:
 
- - Codestyle checks.
+- Codestyle checks.
- - Execute Tests and Code Coverage
+- Execute Tests and Code Coverage
- - Package Tarball Generation
+- Package Tarball Generation
- - Documentation Generation
+- Documentation Generation
- - Validate dependency licenses
+- Validate dependency licenses
 
 Projects which are browser based must also be able to do:
 
- - Unit tests in Firefox and Chromium.
+- Unit tests in Firefox and Chromium.
 
 Projects which are server based must also be able to do:
 
- - Unit tests in Node.js.
+- Unit tests in Node.js.
 
 Projects which require translation must also be able to do:
 
- - Translation import/export and merge for translated objects.
+- Translation import/export and merge for translated objects.
 
 Specific commands
 -----------------
@@ -29,31 +29,31 @@ Specific commands
 The following commands must be supported at the root of a clean tree, in
 order to initialize your project.
 
-  :code:`npm install`
+``npm install``
     This command installs all of the project's dependencies.
 
 To drive the above required steps, the following commands should be
 supported at the root of an initialized tree.
 
-  :code:`npm test`
+``npm test``
     This command executes all available test suites, and generate
     appropriate code coverage reports.
-  :code:`npm run lint`
+``npm run lint``
     This command performs codestyle checks against the project.
-  :code:`npm pack`
+``npm pack``
     This command generates a release tarball.
-  :code:`npm publish <tarball> --no-scripts`
+``npm publish <tarball>--no-scripts``
     This command will publish a release tarball to npm. It may not be
     necessary for all projects.
-  :code:`npm run document`
+``npm run document``
     This command builds documentation for the project.
 
 The following commands are still under discussion:
 
-  :code:`npm run license`
+``npm run license``
     This command ensures that no incompatible licenses have accidentally been
     included.
-  :code:`npm run translate`
+``npm run translate``
     This command imports translations into this project, if necessary.
 
 
@@ -80,13 +80,13 @@ Requirements Listing
 Each project should list its runtime, peer, and development dependencies
 in package.json and (if applicable) bower.json.
 
-  :code:`dependencies`
+``dependencies``
     Packages required by your project to run in production. These should
     never use fuzzy version matching.
-  :code:`devDependencies`
+``devDependencies``
     Packages that are required by your project during the test and build
     phase. These should never use fuzzy version matching.
-  :code:`peerDependencies`
+``peerDependencies``
     Packages that are used to run your project, but whose version does not
     strictly matter. For example, eslint-config-openstack has eslint as a
     peer dependency.
@@ -104,7 +104,7 @@ expected output.
 
 Codestyle Checks
 ================
-:Command: :code:`npm run lint`
+:Command: ``npm run lint``
 
 OpenStack requires the custom npm script 'lint' to execute our codestyle
 checks. The tool we use is called `ESLint`_, and our rules are published to npm
@@ -112,69 +112,70 @@ as eslint-config-openstack_.
 
 Executing Tests and Code Coverage
 =================================
-:Command: :code:`npm test`
+:Command: ``npm test``
 
 OpenStack requires a sane testing and code coverage strategy for each
 project, though we do not prescribe the tools and coverage threshold, as
 these may differ based on circumstance and project type. Generated test
-reports should be placed in :code:`./reports` in your projects' root directory.
+reports should be placed in `./reports` in your projects' root directory.
-Generated coverage output should similarly be placed in :code:`./cover`.
+Generated coverage output should similarly be placed in `./cover`.
 
 Package Tarball Generation
 ==========================
-:Command: :code:`npm pack`
+:Command: ``npm pack``
 
-OpenStack uses :code:`npm pack` to generate a release tarball, which will
+OpenStack uses ``npm pack`` to generate a release tarball, which will
-compile all files listed in :code:`package.json`. If your project requires
+compile all files listed in `package.json`. If your project requires
 concatenation, minification, or any other preprocessing to create a valid
-tarball, you may use the npm :code:`prepublish` hook to trigger these steps.
+tarball, you may use the npm `prepublish` hook to trigger these steps.
 
 All packages should include:
 
- - A README
+- A README
- - A LICENSE file
+- A LICENSE file
- - All source code
+- All source code
 
 Generate Documentation
 ======================
-:Command: :code:`npm run document`
+:Command: ``npm run document``
 
 In order to reuse existing templates, styles, and tooling, OpenStack uses
 Sphinx to generate our JavaScript Project documentation.
 
 In addition to the normal PTI :ref:`pti-documentation` requirements, Javascript
-projects are recommended to provide an :code:`npm run document` command for
+projects are recommended to provide an `npm run document` command for
 developer convenience that should:
 
 * Either install any needed distro dependencies from the ``doc`` tag in
   ``bindep.txt`` or emit an error if they are not installed.
 * Install Python dependencies for Sphinx from ``doc/requirements.txt``.
-* Execute ``sphinx-build -b html doc/source doc/build``
+* Execute ``sphinx-build-b html doc/source doc/build``
 
 The project infrastructure will not use ``npm`` to build the documentation.
 Therefore it is **STRONGLY** discouraged for people to put additional logic
-into the :code:`npm run document` command. Additional logic needed around
+into the `npm run document` command. Additional logic needed around
 Sphinx generation should go into Sphinx plugins which should be listed in
 ``doc/requirements.txt``.
 
 Generate Release Notes
 ======================
-:Command: :code:`npm run releasenotes`
+:Command: ``npm run releasenotes``
 
 OpenStack uses `reno <https://docs.openstack.org/reno/latest/>`_ for generating
 release notes.
 
 In addition to the normal PTI :ref:`pti-documentation` requirements, Javascript
-projects are recommended to provide an :code:`npm run releasenotes` command for
+projects are recommended to provide an `npm run releasenotes` command for
 developer convenience that should:
 
 * Either install any needed distro dependencies from the ``releasenotes`` tag
   in ``bindep.txt`` or emit an error if they are not installed.
-* Execute: ``sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html``
+* Execute: ``sphinx-build -a -E -W -d releasenotes/build/doctrees-b html
+  releasenotes/source releasenotes/build/html``
 
-The project infrastructure will not use :code:`npm run releasenotes` to build
+The project infrastructure will not use `npm run releasenotes` to build
 the release notes. Therefore it is **STRONGLY** discouraged for people to put
-additional logic into the :code:`npm run releasenotes` command. Additional
+additional logic into the `npm run releasenotes` command. Additional
 logic needed should go into reno.
 
 .. _NPM package scripts: https://docs.npmjs.com/misc/scripts

reference/pti/python.rst

@@ -6,16 +6,16 @@ Project Testing Interface: Python
 
 Each python project must be able to do:
 
- - Unit tests for python2.7
+- Unit tests for python2.7
- - Codestyle checks
+- Codestyle checks
- - Testing Coverage Report
+- Testing Coverage Report
- - Source Tarball Generation
+- Source Tarball Generation
- - Translations import/export and merge for translated projects
+- Translations import/export and merge for translated projects
- - Documentation generation
+- Documentation generation
 
 Projects which are compatible with Python 3 must also be able to do:
 
- - Unit tests for python3.5
+- Unit tests for python3.5
 
 Specific commands
 -----------------
@@ -23,21 +23,21 @@ Specific commands
 To drive the above tasks, the following commands should be supported in a clean
 tree:
 
- - tox -epy27
+- ``tox -e py27``
- - tox -epep8
+- ``tox -e pep8``
- - tox -ecover
+- ``tox -e cover``
- - python setup.py sdist
+- ``python setup.py sdist``
- - python setup.py bdist_wheel
+- ``python setup.py bdist_wheel``
- - sphinx-build -W -b html doc/source doc/build
+- ``sphinx-build -W -b html doc/source doc/build``
 
 Projects that are translated should also support:
 
- - tox -evenv python setup.py extract_messages
+- ``tox -e venv python setup.py extract_messages``
- - tox -evenv python setup.py update_catalog
+- ``tox -e venv python setup.py update_catalog``
 
 Projects which are compatible with Python 3 must also be able to do:
 
- - tox -epy35
+- ``tox -e py35``
 
 Some basic prerequisites for test running (system packages, database
 configuration, custom filesystem types) are acceptable as long as they are
@@ -159,7 +159,7 @@ a ``releasenotes`` environment for tox that will run
   sphinx-build -a -E -W -d releasenotes/build/doctrees -b html \
       releasenotes/source releasenotes/build/html
 
-The project infrastructure will not use ``tox -ereleasenotes`` to build the
+The project infrastructure will not use ``tox -e releasenotes`` to build the
 documentation. Therefore it is **STRONGLY** discouraged for people to put
 additional logic into the command section of that tox environment. Additional
 logic needed around releasenotes generation should go into reno.