Merge pull request richardbarran#26 from richardbarran/documentation

Documentation: switch to using Sphinx

README.rst

@@ -1,129 +1,11 @@
-.. Note: the README is formatted as reStructedText as the plan is to (one day) move most of it into a 
-   Sphinx-generated official documentation for Photologue :-)
-
 Photologue
 ==========
 
 Improved image management for the Django web framework.
 
-
-Installation
-------------
-
-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::
-
-    manage.py shell
-    >>> import photologue
-    >>> 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/>`_.
-
-Configure Your Django Settings
-------------------------------
-
-#. Add 'photologue' to your ``INSTALLED_APPS`` setting::
-
-    INSTALLED_APPS = (
-         # ...other installed applications,
-         'photologue',
-    )
-
-#. Confirm that your `MEDIA_ROOT <https://docs.djangoproject.com/en/1.4/ref/settings/#media-root>`_ and
-   `MEDIA_URL <https://docs.djangoproject.com/en/1.4/ref/settings/#std:setting-MEDIA_URL>`_ settings 
-   are correct (Photologue will store uploaded files in a folder called 'photologue' under your ``MEDIA_ROOT``).
-
-Add the urls
-------------
-
-Add photologue to your projects urls.py file::
-
-    urlpatterns += patterns('',
-        ...
-        (r'^photologue/', include('photologue.urls')),
-    )
-    
-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::
-
-    python manage.py plinit
-
-
-Instant Photo Gallery
----------------------
-
-Photologue comes with basic templates for galleries and photos. You can of course override them, or completely
-replace them. Note that all Photologue templates inherit from ``photologue/root.html``, which itself just inherits from
-a site-wide ``base.html`` - you can change this to use a different base template.
-
 Additional Documentation and Support
 ------------------------------------
 
-`Offical docs are available on Google Code <http://code.google.com/p/django-photologue/w/list>`_ (Photologue is 
-in the process of tranferring from Google Code to Github).
-
 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>`_.
 
-Contributing to Photologue
---------------------------
-
-Contributions are always very welcome.
-
-Workflow
-^^^^^^^^
-Django-photologue is hosted on Github, so if you have not already done so, read the excellent
-`Github help pages <https://help.github.com/articles/fork-a-repo>`_. We try to keep the workflow
-as simple as possible, so we more-or-less follow the recommendations in the 
-`"GitHub Flow" blog post <http://scottchacon.com/2011/08/31/github-flow.html>`_.
-
-* The "more or less" is because we don't do immediate releases.
-* One very important point is: don't take it personaly if your pull request is rejected at first; view a pull
-  request as the start of a conversation, with the goal of improving your code, so that it is of the best 
-  possible quality when it gets merged into Photologue.
-
-Coding style
-^^^^^^^^^^^^
-Nothing surprising here - just try to `follow the conventions used by Django itself 
-<https://docs.djangoproject.com/en/1.4/internals/contributing/writing-code/>`_.
-
-New features
-^^^^^^^^^^^^
-If you’re interested in developing a new feature for Photologue, it is recommended that you first 
-discuss it on the `mailing list <http://groups.google.com/group/django-photologue>`_ so as not to 
-do any work that will not get merged in anyway.
-
-Unit tests
-^^^^^^^^^^
-Including unit tests with your contributions will earn you bonus points, maybe even a beer. So write
-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.
-
-.. note:: Right now, this README is the only up-to-date documentation for Photologue (the plan is to use Sphinx in the near future). 
-
-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!

docs/.gitignore

@@ -0,0 +1 @@
+_build

docs/Makefile

@@ -0,0 +1,153 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/django-photologue.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/django-photologue.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/django-photologue"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/django-photologue"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."