django-thumbnail-works Installation Instructions
-This file contains information on how to download and install
-django-thumbnail-works in your system.
+This section contains information about how to download and install
+django-thumbnail-works in your system. It also contains brief instructions about how
+to build the included documentation.
-This application requires Python 2.3 or later, and a functional installation
-of Django. You can obtain Python from http://www.python.org/ and Django from
+This application requires Python_ 2.4 or later, and a functional installation
+.. _Python: http://python.org
+.. _Django: http://www.djangoproject.com
Detailed information about the minimum supported Django version and other
-Python modules that may be required in order to run this software are
-available in the `requirements.txt` file.
+Python modules that may be required in order to run this software is shown
+.. literalinclude:: ../requirements.txt
+This information exists in the ``requirements.txt`` file inside the
+django-thumbnail-works distribution package. If ``pip`` is used to install this software,
+then all these dependencies will also be installed.
-You can download the latest django-thumbnail-works releases either from the
-project page at the Python Package Index (PyPI):
- * http://pypi.python.org/pypi/django-thumbnail-works
+You can download the latest django-thumbnail-works releases from the `project page`_ at
+the *Python Package Index* (PyPI).
-Or you can clone the project's public source code repository and then
-check-out any stable release, all of which are tagged:
+.. _`project page`: http://pypi.python.org/pypi/django-thumbnail-works
+Alternatively, you can clone the project's public source code repository
+and then check-out any stable release, all of which are tagged::
hg clone https://source.codetrax.org/hgroot/django-thumbnail-works
-To install django-thumbnail-works, use the provided installation script:
+To install django-thumbnail-works, use the provided installation script::
-If you have the Python `easy_install` utility available, you can
-also type the following to download and install in one step:
- easy_install -Z django-thumbnail-works
-(the `-Z` flag is required to force `easy_install` to do a normal
-source install rather than a zipped egg; django-thumbnail-works cannot be
-used from a zipped egg install)
-Or if you're using `pip`:
+You can install ``django-thumbnail-works`` using ``pip``::
pip install django-thumbnail-works
-Or if you'd prefer you can simply place the `thumbnail_works` directory,
-which exists under `src`, somewhere on your Python path, or symlink to it
-from somewhere on your Python path.
+Or use ``easy_install``::
+ easy_install -Z django-thumbnail-works
+Note: the ``-Z`` flag is required to force ``easy_install`` to do a normal
+source install rather than a zipped egg; django-thumbnail-works cannot be
+used from a zipped egg install.
+Alternatively, you can simply place the ``thumbnail_works`` directory,
+which exists under the ``src`` directory, somewhere on your Python path,
+or symlink to it from somewhere on your Python path.
+Finally, it is also possible to install this application directly from
+the `source code repository`_ using ``pip``::
+ pip install -e hg+https://source.codetrax.org/hgroot/django-thumbnail-works#egg=django-thumbnail-works
+The above command will install the latest development release of
+To install a stable release directly from the `source code repository`_,
+for instance, the ``0.1.0`` release, run the following command::
+ pip install -e hg+https://firstname.lastname@example.org#egg=django-thumbnail-works-0.1.0
+Please note that the mercurial_ source control management tool is required
+.. _mercurial: http://mercurial.selenic.com/
+.. _`source code repository`: https://source.codetrax.org/hgroot/django-thumbnail-works
+How to build the documentation
+This project's documentation is located in source form under the ``docs``
+directory. In order to convert the documentation to a format that is
+easy to read and navigate you need the ``sphinx`` package.
+You can install ``sphinx`` using ``pip``::
+Once ``sphinx`` is installed, change to the ``docs`` directory, open a shell
+and run the following command::
+This will build a HTML version of the documentation. You can read the
+documentation by opening the following file in any web browser::