From 980787ef8ce9fa05c75795738df69375c9fdd61f Mon Sep 17 00:00:00 2001
From: Doug Hellmann <doug.hellmann@dreamhost.com>
Date: Wed, 25 Apr 2012 19:45:44 -0400
Subject: add some developer instructions and links ot the source repo and bug
 tracker

---
 docs/source/developers.rst | 75 ++++++++++++++++++++++++++++++++++++++++++++++
 docs/source/index.rst      |  2 ++
 docs/source/install.rst    | 37 +++++++++++++++++++++++
 3 files changed, 114 insertions(+)
 create mode 100644 docs/source/developers.rst
 create mode 100644 docs/source/install.rst

(limited to 'docs')

diff --git a/docs/source/developers.rst b/docs/source/developers.rst
new file mode 100644
index 0000000..052692e
--- /dev/null
+++ b/docs/source/developers.rst
@@ -0,0 +1,75 @@
+================
+ For Developers
+================
+
+If you would like to contribute to cliff directly, these instructions
+should help you get started.  Patches, bug reports, and feature
+requests are all welcome through the `GitHub project
+<https://github.com/dreamhost/cliff>`_.  Contributions in the form of
+patches or pull requests are easier to integrate and will receive
+priority attention.
+
+.. note::
+
+  Before contributing new features to clif core, please consider
+  whether they should be implemented as an extension instead. The
+  architecture is highly pluggable precisely to keep the core small.
+
+Building Documentation
+======================
+
+The documentation for cliff is written in reStructuredText and
+converted to HTML using Sphinx. The build itself is driven by make.
+You will need the following packages in order to build the docs:
+
+- Sphinx
+- docutils
+
+Once all of the tools are installed into a virtualenv using
+pip, run ``make html`` to generate the HTML version of the
+documentation::
+
+    $ make docs
+    (cd docs && make clean html)
+    sphinx-build -b html -d build/doctrees   source build/html
+    Running Sphinx v1.1.3
+    loading pickled environment... done
+    building [html]: targets for 1 source files that are out of date
+    updating environment: 1 added, 1 changed, 0 removed
+    reading sources... [100%] index                                                 
+    looking for now-outdated files... none found
+    pickling environment... done
+    done
+    preparing documents... done
+    writing output... [100%] index                                                  
+    writing additional files... genindex search
+    copying static files... done
+    dumping search index... done
+    dumping object inventory... done
+    build succeeded, 2 warnings.
+
+    Build finished. The HTML pages are in build/html.
+    
+The output version of the documentation ends up in
+``./cliff/docs/build/html`` inside your sandbox.
+
+Running Tests
+=============
+
+The test suite for clif uses tox_, which must be installed separately
+(``pip install tox``).
+
+To run the tests under Python 2.7 and 3.2, run ``tox`` from the top
+level directory of the git repository.
+
+To run tests under a single version of Python, specify the appropriate
+environment when running tox::
+
+  $ tox -e py27
+
+Add new tests by modifying an existing file or creating new script in
+the ``tests`` directory.
+
+.. _tox: http://codespeak.net/tox
+
+.. _developer-templates:
diff --git a/docs/source/index.rst b/docs/source/index.rst
index c52580b..a207b9a 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -15,6 +15,8 @@ Contents:
    demoapp
    list_commands
    classes
+   install
+   developers
 
 
 Indices and tables
diff --git a/docs/source/install.rst b/docs/source/install.rst
new file mode 100644
index 0000000..1bd67d0
--- /dev/null
+++ b/docs/source/install.rst
@@ -0,0 +1,37 @@
+==============
+ Installation
+==============
+
+Python Versions
+===============
+
+cliff is being developed under Python 2.7 and tested with Python 3.2.
+
+.. _install-basic:
+
+Basic Installation
+==================
+
+cliff should be installed into the same site-packages area where the
+application and extensions are installed (either a virtualenv or the
+global site-packages). You may need administrative privileges to do
+that.  The easiest way to install it is using pip_::
+
+  $ pip install cliff
+
+or::
+
+  $ sudo pip install cliff
+
+.. _pip: http://pypi.python.org/pypi/pip
+
+Source Code
+===========
+
+The source is hosted on github: https://github.com/dreamhost/cliff
+
+Reporting Bugs
+==============
+
+Please report bugs through the github project:
+https://github.com/dreamhost/cliff/issues
-- 
cgit v1.2.1