From f4b46e56bea1b0b4e7ba9096a85f4b9e3ca1b911 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Mon, 15 Oct 2018 13:57:35 +0100 Subject: [PATCH] docs: Misc updates I tried splitting these into separate commits but the splits were too abstract. Change-Id: I996c920e861d7507d0d0bb41ba4f5e65362e0b44 Signed-off-by: Stephen Finucane Story: 1388398 Task: 584 --- doc/source/developing.rst | 14 ++++------ doc/source/index.rst | 11 +------- doc/source/installation.rst | 54 +++++++++++++++++++------------------ 3 files changed, 34 insertions(+), 45 deletions(-) diff --git a/doc/source/developing.rst b/doc/source/developing.rst index 9eded603..fa2c2a1f 100644 --- a/doc/source/developing.rst +++ b/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 - cached copy (it needs to be located in a .gerrit directory at the +* Internet access to download the ``gerrit.war`` file, or a locally + 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 py26 - tox -e py32 - tox -e py33 - -depending on what Python interpreter would you like to use. + tox -e py37 diff --git a/doc/source/index.rst b/doc/source/index.rst index 7f289990..0a132212 100644 --- a/doc/source/index.rst +++ b/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` - diff --git a/doc/source/installation.rst b/doc/source/installation.rst index fa7cc4c9..530f9bf5 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -5,16 +5,15 @@ Installing git-review ===================== -``git-review`` can be often be installed via system packages, ``pypi`` -releases or other platform-specific methods. See -``__ for platform -information. +``git-review`` can be installed from PyPI or system packages. To install from +PyPI, run:: -For assistance installing pacakges from ``pypi`` on your OS check out -`get-pip.py `__. + pip install git-review -For installation from source simply add ``git-review`` to your $PATH -after installing the dependencies listed in requirements.txt +Alternatively, refer to the `MediaWiki Guide`__ for information on installing +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 `__ 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 -the gerrit remote. Assuming that file is present, git-review should +called ``.gitreview`` at the root of the repository with information about +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), -defaultremote (default: gerrit). +Optional values: ``port`` (default: ``29418``), ``defaultbranch`` (default: +``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', - but this can be overridden with the 'defaultremote' configuration + if it does not already exist. By default, the remote name is ``gerrit``, + 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 -.git/hooks/ with the other git hook scripts. +``~/.config/git-review/hooks/`` and one local to the repository stored in +``.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, -git-review will exit with the a custom shell exit code 71. +If the script returns with an exit status different than zero, git-review will +exit with the custom shell exit code ``71``.