George Notaras avatar George Notaras committed eb984d7

Updated supplemental files

Comments (0)

Files changed (5)

 
  * George Notaras <gnot [at] g-loaded.eu>, CodeTRAX.org
 
-The following people have contributed to this project in one way or another:
-
- *
 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.
 
 
 Requirements
-------------
-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
-http://www.djangoproject.com/.
+============
+
+This application requires Python_ 2.4 or later, and a functional installation
+of Django_.
+
+.. _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
+below:
+
+.. 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.
 
 
 Download
---------
-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
     hg tags
-    hg update 0.1.1
+    hg update 0.1.0
 
 
 Install
--------
-To install django-thumbnail-works, use the provided installation script:
+=======
+
+To install django-thumbnail-works, use the provided installation script::
 
     python setup.py install
 
-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
+django-thumbnail-works.
+
+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://source.codetrax.org/hgroot/django-thumbnail-works@0.1.0#egg=django-thumbnail-works-0.1.0
+
+Please note that the mercurial_ source control management tool is required
+for this operation.
+
+.. _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``::
+
+    pip install sphinx
+
+Or ``easy_install``::
+
+    easy_install sphinx
+
+Once ``sphinx`` is installed, change to the ``docs`` directory, open a shell
+and run the following command::
+
+    make html
+
+This will build a HTML version of the documentation. You can read the
+documentation by opening the following file in any web browser::
+
+    docs/_build/html/index.html
+
 include AUTHORS
-include BUGS
 include INSTALL
 include LICENSE
 include NOTICE
 include README
-include SUPPORT
 include MANIFEST.in
 include requirements.txt
 include setup.cfg
 include setup.py
 recursive-include src/thumbnail_works *.py
+graft docs
 This product includes software developed at:
-  * CodeTRAX (http://www.codetrax.org/)
-  * G-Loaded Journal (http://www.g-loaded.eu/)
+
+* CodeTRAX (http://www.codetrax.org/)
+* G-Loaded Journal (http://www.g-loaded.eu/)
 
 Copyright 2010 George Notaras <gnot [at] g-loaded.eu>
 
 Brand names include, but are not limited to:
 
-  * django-thumbnail-works
-  * thumbnail_works
-  * CodeTRAX
-  * G-Loaded Journal
+* django-thumbnail-works
+* thumbnail_works
+* CodeTRAX
+* G-Loaded Journal
 
 The aforementioned names must not appear in the names of products derived from
 this software without prior written permission of George Notaras.
-django-thumbnail-works README
+django-thumbnail-works
 ========================================================================
-django-thumbnail-works provides an enhanced ImageField that generates and
-manages thumbnails of the uploaded image.
 
-Project Development Web Site:
- * https://www.codetrax.org/projects/django-thumbnail-works
+django-thumbnail-works adds thumbnail support to the default ImageField.
 
-Public Source Code Repository:
- * https://source.codetrax.org/hgroot/django-thumbnail-works
+Licensed under the *Apache License version 2.0*. More licensing information
+exists in the license_ section.
 
 
-How this distribution package is organized
-========================================================================
-The following list outlines the kind of information each of the files of this
-distribution package contains:
+Features
+========
 
- * AUTHORS  : List of all authors and contributors.
- * BUGS     : Information about how to file bug reports or ask for new features.
- * HELP     : Instructions on how to use this software.
- * INSTALL  : Information on how to install this application.
- * LICENSE  : The terms of the license that governs your use of this software.
- * NOTICE   : Copyright, trademark, attribution and sponsorship information.
- * SUPPORT  : Information on how to get support for this software.
- * README   : This file.
+- Feature A
+- Feature B
 
 
-How to read the HELP document
-========================================================================
-The HELP document is written in reStructuredText (rst). Although
-reStructuredText is an easy-to-read plain text markup format, it is
-recommended to convert it to HTML for a better reading experience.
+Documentation
+=============
 
-In order to convert this document to HTML you need `docutils`, which
-you can install in your system using `pip`::
+Apart from the `django-thumbnail-works Online Documentation`_, more information about the
+installation, configuration and usage of this application may be available
+at the project's wiki_.
 
-    pip install docutils
+.. _`django-thumbnail-works Online Documentation`: http://packages.python.org/django-thumbnail-works
+.. _wiki: http://www.codetrax.org/projects/django-thumbnail-works/wiki
 
-Or `easy_install`:
 
-    easy_install docutils
+Donations
+=========
 
-Once `docutils` is installed, you can use the `rst2html.py` utility to
-perform the conversion:
+A significant amount of time and effort has gone into developing this software
+and writing this documentation. So, the production of this software has not
+been free from cost. It is highly recommended that, if you use this software
+*in production*, you should consider making a donation.
 
-    rst2html.py HELP help.html
+To make a donation, please visit the CodeTRAX `donations page`_ which contains
+a PayPal_ *donate* button.
 
-Then use any web browser to view the exported `help.html` file.
+Thank you for considering making a donation to django-thumbnail-works.
+
+.. _`donations page`: https://source.codetrax.org/donate.html
+.. _PayPal: https://www.paypal.com
+
+
+Bugs and feature requests
+=========================
+
+In case you run into any problems while using this application or think that
+a new feature should be implemented, it is highly recommended you submit_ a new
+report about it at the project's `issue tracker`_.
+
+Using the *issue tracker* is the recommended way to notify the authors about
+bugs or make feature requests. Also, before submitting a new report, please
+make sure you have read the `new issue guidelines`_.
+
+.. _submit: http://www.codetrax.org/projects/django-thumbnail-works/issues/new
+.. _`issue tracker`: http://www.codetrax.org/projects/django-thumbnail-works/issues
+.. _`new issue guidelines`: http://www.codetrax.org/NewIssueGuidelines
+
+
+Support
+=======
+
+CodeTRAX does not provide support for django-thumbnail-works.
+
+You can still get community support at the `Community Support Forums`_:
+
+.. _`Community Support Forums`: http://www.codetrax.org/projects/django-thumbnail-works/boards
 
 
 License
-========================================================================
+=======
+
 Copyright 2010 George Notaras <gnot [at] g-loaded.eu>
 
-Licensed under the Apache License, Version 2.0 (the "License");
+Licensed under the *Apache License, Version 2.0* (the "*License*");
 you may not use this file except in compliance with the License.
 
 Unless required by applicable law or agreed to in writing, software
 See the License for the specific language governing permissions and
 limitations under the License.
 
-A copy of the License exists in the product distribution; the LICENSE file.
-For copyright notes please read the NOTICE file.
-
+A copy of the License exists in the product distribution; the *LICENSE* file.
+For copyright and other important notes regarding this release please read
+the *NOTICE* file.
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.