Merge pull request #27 from richardbarran/documentation

Documentation tweaks.
richardbarran · Sep 3, 2012 · d98b55a · d98b55a
2 parents 64a9416 + e56ab0c
commit d98b55a
Show file tree

Hide file tree

Showing 8 changed files with 52 additions and 20 deletions.
diff --git a/CHANGELOG.txt b/CHANGELOG.txt
@@ -5,6 +5,7 @@ List of changes:
 
 - added a sitemap.xml.
 - added some templatetags.
+- started using Sphinx for managing documentation.
 
 ===== 2.4 (13/08/2012) ====
 

diff --git a/README.rst b/README.rst
@@ -1,10 +1,14 @@
 Photologue
 ==========
 
-Improved image management for the Django web framework.
+Improved image management and photo gallery application for the Django web framework.
 
-Additional Documentation and Support
-------------------------------------
+Documentation
+-------------
+Please head over to our `online documentation <http://django-photologue.readthedocs.org/en/latest/index.html>`_ for instructions on installing and configuring this application.
+
+Support
+-------
 
 If you have any questions or need help with any aspect of Photologue then please `join the mailing list
 <http://groups.google.com/group/django-photologue>`_.

diff --git a/docs/essentials/contributing.rst b/docs/essentials/contributing.rst
@@ -34,10 +34,13 @@ plenty of tests.
 
 Documentation
 -------------
-Keeping the documentation up-to-date is very important - so if your code changes how Photologue works,
-check that the documentation is still accurate.
+Keeping the documentation up-to-date is very important - so if your code changes
+how Photologue works, please check that the documentation is still accurate, and
+update it if required.
 
-.. note:: Right now, this README is the only up-to-date documentation for Photologue (the plan is to use Sphinx in the near future). 
+We use `Sphinx <http://sphinx.pocoo.org/>`_ to prepare the documentation; please refer to the excellent docs
+on that site for help.
 
-Oh, and in a more general sense, the CHANGELOG is part of the documentation - so if your patch needs 
-the end user to be aware of something e.g. need to run a South migration, mention it in the CHANGELOG!
+P.S. The CHANGELOG is part of the documentation :-) so if your patch needs the
+end user to do something - e.g. run a South migration - don't forget to update
+it!
diff --git a/docs/essentials/installation.rst b/docs/essentials/installation.rst
@@ -9,9 +9,6 @@ The easiest way to install Photologue is with pip::
 
    pip install django-photologue
 
-Photologue uses the Python Imaging Library and South; these will be installed
-automatically if they are not already there.
-
 You can verify Photologue is available to your project by running the following
 commands from within your project directory::
 
@@ -20,17 +17,15 @@ commands from within your project directory::
     >>> photologue.VERSION
     (2, 0, 'rc1')
 
-Tracking the Development Version
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The current development version of Photologue can be checked out via Git from the project site using the following command::
-
-    git clone git://github.com/jdriscoll/django-photologue.git
-
 Dependencies
 ------------
 
-Photologue uses the Django admin app, `so enable it if you have not already done so <https://docs.djangoproject.com/en/1.4/ref/contrib/admin/>`_.
+* `PIL <http://www.pythonware.com/products/pil/>`_.
+* `South <http://south.aeracode.org/>`_.
+
+These 2 apps will be installed automatically if they are not already there.
+
+Photologue also uses the Django admin app, `so enable it if you have not already done so <https://docs.djangoproject.com/en/1.4/ref/contrib/admin/>`_.
 
 Configure Your Django Settings
 ------------------------------
@@ -40,6 +35,7 @@ Configure Your Django Settings
     INSTALLED_APPS = (
          # ...other installed applications,
          'photologue',
+         'south',
     )
 
 #. Confirm that your `MEDIA_ROOT <https://docs.djangoproject.com/en/1.4/ref/settings/#media-root>`_ and
@@ -59,7 +55,12 @@ Add photologue to your projects urls.py file::
 Sync Your Database
 ------------------
 
-Run the Django 'syncdb' command to create the appropriate tables. After the database in initialized, run the following command to initialize Photologue::
+Use South to setup the new tables::
+
+    python manage.py migrate photologue
+
+After the database in initialized, run the following command to setup some 
+default values for Photologue::
 
     python manage.py plinit
 

diff --git a/docs/images/screenshot_mahoTBD.png b/docs/images/screenshot_mahoTBD.png
diff --git a/docs/images/screenshot_mahoTBD_admin.png b/docs/images/screenshot_mahoTBD_admin.png
diff --git a/docs/index.rst b/docs/index.rst
@@ -20,6 +20,7 @@ Contents:
 
     essentials/installation
     essentials/contributing
+    misc/examples_and_forks
 
 Indices and tables
 ==================

diff --git a/docs/misc/examples_and_forks.rst b/docs/misc/examples_and_forks.rst
@@ -0,0 +1,22 @@
+##################
+Examples and forks
+##################
+
+Here are some examples of Photologue "in the wild", together with a few interesting
+forks of the project.
+
+The following sites are using Photologue to manage their images.
+If you're using Photologue and would like to have your site linked, just open
+a new issue with the URL and a description of the site - or change the docs 
+yourself and send a pull request. 
+
+`mahotribalbellydance.com <http://www.mahotribalbellydance.com/photologue/gallery/page/1/>`_
+
+A customised version of Photologue (integrated with a Lightbox):
+
+.. image:: ../images/screenshot_mahoTBD.png
+    :width: 600px
+    :align: center
+
+
+