Files

Darragh Bailey 65cb8e2004 Add basic documentation and migrate README & USAGE

Where documentation is being moved about, corrections will be avoided
to allow for easier following of conversion separated from rewriting.

* Set up some simple documentation to describe basic details of
  git-upstream and installation.
* Migrate details from README into dedicated subcommands rst doc.
* Consolidate installation instructions from USAGE into
  installation rst page.
* Move remainder of USAGE into dedicated workflows rst and match the
  existing markdown layout.

Change-Id: Ie73d64ae7cb0e96060729638da382c901d5d68e7

2016-11-14 15:18:54 +00:00

3.0 KiB

Raw Blame History

Installation

To install git-upstream from pypi, run:

pip install --user git-upstream

Alternatively, the current release can be installed system-wide from pypi:

sudo pip install git-upstream

Installing directly from source is possible, first clone and then install using pip:

git clone https://git.openstack.org/openstack/git-upstream.git
cd git-upstream
pip install .

Or setup.py:

git clone https://git.openstack.org/openstack/git-upstream.git
cd git-upstream
python setup.py install

Or alternatively:

git clone https://git.openstack.org/openstack/git-upstream.git
cd git-upstream
easy_install .

If you want command line completion (using tab), install the provided "bash completion" file

mkdir ~/bin && cp ./bash_completion/git-upstream ~/bin
echo ". ~/bin/git-upstream" >> ~/.bash_profile

Verify your installation.

pip show git-upstream
---
Name: git-upstream
Version: 0.12.1
Summary: git tool to help manage upstream repositories
Home-page: https://pypi.python.org/pypi/git-upstream
Author: Darragh Bailey
Author-email: dbailey@hpe.com
License: Apache License (2.0)
Location: /home/<username>/.local/lib/python2.7/site-packages
Requires: argcomplete, pbr, six, GitPython

git-upstream --help
usage: git-upstream [--version] [-h] [-q | -v] <command> ...

[...]

Installing for Development

A virtual environment is recommended for development. For example, git-upstream may be installed from the top level directory:

virtualenv .venv
source .venv/bin/activate
pip install -r test-requirements.txt -e .

Generating Documentation

Documentation is included in the doc folder. To generate docs locally execute the command:

tox -e docs

The generated documentation is then available under doc/build/html/index.html.

Note: When behind a proxy it is necessary to use TOX_TESTENV_PASSENV to pass any proxy settings for this test to be able to check links are valid.

Unit Tests

Unit tests have been included and are in the git_upstream/tests folder. Many unit tests samples are included as example scenarios in our documentation to help explain how git-upstream handles various use cases. To run the unit tests, execute the command:

tox -e py34,py27

Note: View tox.ini to run tests on other versions of Python, generating the documentation and additionally for any special notes on building one of the scenarios to allow direct inspection and manual execution of git-upstream with various scenarios.

The unit tests can in many cases be better understood as being closer to functional tests.

Test Coverage

To measure test coverage, execute the command:

tox -e cover

3.0 KiB Raw Blame History