pti: Misc fixes

Add some links, fix some formatting, and generally tidy things up here.

Change-Id: I6d4326f6c8e38fa7f57b479cba8c455759da24dd
Signed-off-by: Stephen Finucane <stephenfin@redhat.com>

reference/pti/python.rst

@@ -6,7 +6,7 @@ Project Testing Interface: Python
 
 Each project containing Python components must be able to do:
 
-- Unit tests for python (see below for version details)
+- Unit tests for Python (see below for version details)
 - Codestyle checks
 - Testing Coverage Report
 - Source Tarball Generation
@@ -47,8 +47,8 @@ Projects that are translated should also support generating and updating their
 
 Some basic prerequisites for test running (system packages, database
 configuration, custom filesystem types) are acceptable as long as they are
-documented in a visible location such as a CONTRIBUTING, TESTING, or README
+documented in a visible location such as a ``CONTRIBUTING.rst``,
-file in the root of the repository.
+``TESTING.rst``, or ``README.rst`` file in the root of the repository.
 
 Requirements Listing
 --------------------
@@ -73,52 +73,66 @@ ease the diagnosis of breakage caused by projects upstream to OpenStack and
 to provide a set of packages known to work together.
 
 Projects may opt into using the constraints in one or more of their
-standard targets via their tox.ini configuration.
+standard targets via their ``tox.ini`` configuration.
 
 Virtual Environment Management
 ------------------------------
 
-To support sensible testing across multiple python versions, we use tox
+To support sensible testing across multiple Python versions, we use tox
 config files in the projects.
 
 Python test running
 -------------------
 
-OpenStack uses stestr as its test runner. stestr should be used for running
+OpenStack uses `stestr`__ as its test runner. *stestr* should be used for
-all python tests, this includes unit tests, functional tests, and integration
+running all Python tests, including unit, functional, and integration tests.
-tests. stestr is used because of its real time subunit output and its support
+*stestr* is used because of its real time subunit output and its support for
-for parallel execution of tests. In addition, stestr only runs tests conforming
+parallel execution of tests. In addition, *stestr* only runs tests conforming
-to the python stdlib unittest model (and extensions on it like testtools). This
+to the Python stdlib unittest model (and extensions on it like `testtools`__).
-enables people to use any test runner they prefer locally. Other popular test
+This enables people to use any test runner they prefer locally. Other popular
-runners often include a testing ecosystem which is tied directly to the runner.
+test runners often include a testing ecosystem which is tied directly to the
-Using these precludes the use of alternative runners for other users.
+runner. Using these precludes the use of alternative runners for other users.
 
 To have a consistent interface via tox between projects' unit test
-jobs the command for running stestr in tox should be set to::
+jobs the command for running *stestr* in tox should be set like so:
 
-    stestr run {posargs}
+.. code-block:: ini
+
+    [testenv]
+    commands =
+        stestr run {posargs}
 
 .. note::
+
     While the use of wrapper scripts can sometimes be useful as a short term
     crutch to work around a specific temporary issues, it should be avoided
     because it creates a divergent experience between projects, and can mask
     real issues.
 
-If there are additional mandatory args needed for running a test suite they
+If there are additional mandatory arguments needed for running a test suite
-can be added before the posargs. (this way the end user experience is the same)
+they can be added before the positional arguments, ensuring the end user
-For example::
+experience remains the same. For example:
 
-    stestr --test-path ./tests/unit run {posargs}
+.. code-block:: shell
+
+    [testenv]
+    commands =
+        stestr --test-path ./tests/unit run {posargs}
 
 However, these arguments should try to be minimized because it just adds to the
 complexity that people will need to understand when running tests on a project.
 
+.. __: https://stestr.readthedocs.io/
+.. __: https://testtools.readthedocs.io/
+
 Coverage Jobs
 -------------
 
 For coverage jobs you need to invoke the test runner in the same way as for the
-normal unit test jobs, but to switch the python executable to be
+normal unit test jobs, but to switch the Python executable to be
-``coverage run``. To do this you need to setup the tox ``cover`` job like::
+``coverage run``. To do this you need to setup the tox ``cover`` job like:
+
+.. code-block:: ini
 
   [testenv:cover]
   setenv =
@@ -137,7 +151,7 @@ Project Configuration
 
 All OpenStack projects use `pbr`__ for consistent operation of setuptools.
 To accomplish this, all ``setup.py`` files only contain a simple setup function
-that enabled pbr. Actual project configuration is then handled in
+that enabled *pbr*. Actual project configuration is then handled in
 ``pyproject.toml`` or ``setup.cfg``.
 
 .. __: https://docs.openstack.org/pbr/latest/
@@ -145,20 +159,20 @@ that enabled pbr. Actual project configuration is then handled in
 Generated Files
 ---------------
 
-ChangeLog and AUTHORS files are generated at setup.py sdist time. This is
+``ChangeLog`` and ``AUTHORS`` files are generated at setup.py sdist time. This
-handled by pbr.
+is handled by pbr.
 
-.mailmap files should exist where a developer has more than one email address
+``.mailmap`` files should exist where a developer has more than one email
-or identity, and should map to the developer's canonical identity.
+address or identity, and should map to the developer's canonical identity.
 
 Translations
 ------------
 
 To support translations processing, projects should have a valid babel config.
-There should be a locale package inside of the top project module, and in that
+There should be a ``locale`` package inside of the top project module, and in that
-dir should be the $project.pot file. For instance, for nova, there should be
+directory should be the ``$project.pot`` file. For instance, the ``.pot`` file
-nova/locale/nova.pot. Babel commands should be configured out output their .mo
+for nova should be found at ``nova/locale/nova.pot``. Babel commands should be
-files in to $project/locale as well.
+configured out output their ``.mo`` files in to ``$project/locale`` as well.
 
 Release Notes
 -------------
@@ -174,4 +188,4 @@ a ``releasenotes`` environment for tox that will run
 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.
+logic needed around release notes generation should go into *reno*.