docs: Misc updates

I tried splitting these into separate commits but the splits were too
abstract.

Change-Id: I996c920e861d7507d0d0bb41ba4f5e65362e0b44
Signed-off-by: Stephen Finucane <stephenfin@redhat.com>
Story: 1388398
Task: 584

doc/source/developing.rst

@@ -9,15 +9,11 @@ following:
 
 * a Java Runtime Environment on the machine to run tests on
 
-* Internet access to download the gerrit.war file, or a locally
+* Internet access to download the ``gerrit.war`` file, or a locally
-  cached copy (it needs to be located in a .gerrit directory at the
+  cached copy (it needs to be located in a ``.gerrit`` directory at the
   top level of the git-review project)
 
-To run git-review integration tests the following commands may by run::
+To run git-review integration tests, use tox. For example, to test against
+Python 3.7::
 
-    tox -e py27
+    tox -e py37
-    tox -e py26
-    tox -e py32
-    tox -e py33
-
-depending on what Python interpreter would you like to use.

doc/source/index.rst

@@ -2,7 +2,7 @@
  git-review
 ============
 
-``git-review`` is a tool that helps submitting git branches to gerrit
+``git-review`` is a tool that helps submitting git branches to Gerrit
 for review.
 
 .. toctree::
@@ -12,12 +12,3 @@ for review.
    usage
    developing
    releasenotes
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-

doc/source/installation.rst

@@ -5,16 +5,15 @@
 Installing git-review
 =====================
 
-``git-review`` can be often be installed via system packages, ``pypi``
+``git-review`` can be installed from PyPI or system packages. To install from
-releases or other platform-specific methods.  See
+PyPI, run::
-`<https://www.mediawiki.org/wiki/Gerrit/git-review>`__ for platform
-information.
 
-For assistance installing pacakges from ``pypi`` on your OS check out
+    pip install git-review
-`get-pip.py <https://pip.pypa.io/en/stable/installing/>`__.
 
-For installation from source simply add ``git-review`` to your $PATH
+Alternatively, refer to the `MediaWiki Guide`__ for information on installing
-after installing the dependencies listed in requirements.txt
+from system packages.
+
+__ https://www.mediawiki.org/wiki/Gerrit/git-review
 
 .. note:: ``git-review`` requires git version 1.8 or greater.
 
@@ -28,22 +27,24 @@ recommended for Windows users.  For earlier Python versions,
 modifying the local install with `win-unicode-console
 <https://github.com/Drekin/win-unicode-console>`__ may also help.
 
+
 Setup
 =====
 
-By default, git-review will look for a remote named 'gerrit' for working
+By default, git-review will look for a remote named ``gerrit`` for working
 with Gerrit. If the remote exists, git-review will submit the current
-branch to HEAD:refs/for/master at that remote.
+branch to ``HEAD:refs/for/master`` at that remote.
 
 If the Gerrit remote does not exist, git-review looks for a file
-called .gitreview at the root of the repository with information about
+called ``.gitreview`` at the root of the repository with information about
-the gerrit remote.  Assuming that file is present, git-review should
+the Gerrit remote.  Assuming that file is present, git-review should
 be able to automatically configure your repository the first time it
 is run.
 
 The name of the Gerrit remote is configurable; see the configuration
 section below.
 
+
 .gitreview file format
 ======================
 
@@ -55,10 +56,10 @@ Example .gitreview file (used to upload for git-review itself)::
     project=openstack-infra/git-review.git
     defaultbranch=master
 
-Required values: host, project
+Required values: ``host``, ``project``
 
-Optional values: port (default: 29418), defaultbranch (default: master),
+Optional values: ``port`` (default: ``29418``), ``defaultbranch`` (default:
-defaultremote (default: gerrit).
+``master``), ``defaultremote`` (default: ``gerrit``).
 
 **Notes**
 
@@ -68,18 +69,20 @@ defaultremote (default: gerrit).
   of the variable.
 
 * Upon first run, git-review will create a remote for working with Gerrit,
-  if it does not already exist. By default, the remote name is 'gerrit',
+  if it does not already exist. By default, the remote name is ``gerrit``,
-  but this can be overridden with the 'defaultremote' configuration
+  but this can be overridden with the ``defaultremote`` configuration
   option.
 
 * You can specify different values to be used as defaults in
-  ~/.config/git-review/git-review.conf or /etc/git-review/git-review.conf.
+  ``~/.config/git-review/git-review.conf`` or
+  ``/etc/git-review/git-review.conf``.
 
-* Git-review will query git credential system for gerrit user/password when
+* git-review will query git credential system for Gerrit user/password when
   authentication failed over http(s). Unlike git, git-review does not persist
-  gerrit user/password in git credential system for security purposes and git
+  Gerrit user/password in git credential system for security purposes and git
   credential system configuration stays under user responsibility.
 
+
 Hooks
 =====
 
@@ -87,13 +90,12 @@ git-review has a custom hook mechanism to run a script before certain
 actions. This is done in the same spirit as the classic hooks in git.
 
 There are two types of hooks, a global one which is stored in
-~/.config/git-review/hooks/ and one local to the repository stored in
+``~/.config/git-review/hooks/`` and one local to the repository stored in
-.git/hooks/ with the other git hook scripts.
+``.git/hooks/`` with the other git hook scripts.
 
 **The script needs be executable before getting executed**
 
-The name of the script is $action-review where action can be
+The name of the script is $action-review where action can be:
-:
 
 * pre - run at first before doing anything.
 
@@ -101,5 +103,5 @@ The name of the script is $action-review where action can be
 
 * draft - run when in draft mode.
 
-if the script returns with an exit status different than zero,
+If the script returns with an exit status different than zero, git-review will
-git-review will exit with the a custom shell exit code 71.
+exit with the custom shell exit code ``71``.