Reviewed Makefile, development environment and contributor guide.

CONTRIBUTING.rst

@@ -24,59 +24,60 @@ Please use the `bugtracker`_ **before** starting some work:
   ``refs #TICKET-ID`` syntax.
 
 
-***************
+******************
-Fork and branch
+Use topic branches
-***************
+******************
 
-* Work in forks and branches.
+* Work in branches.
 
 * Prefix your branch with the ticket ID corresponding to the issue. As an
   example, if you are working on ticket #23 which is about contribute
   documentation, name your branch like ``23-contribute-doc``.
 
 * If you work in a development branch and want to refresh it with changes from
-  master, please `rebase`_ or `merge-based rebase`_, i.e. don't merge master.
+  master, please `rebase`_ or `merge-based rebase`_, i.e. do not merge master.
 
 
-*******************************
+***********
-Setup a development environment
+Fork, clone
-*******************************
+***********
 
-System requirements: `Python`_ version 2.7 and `tox`_ (you may use a
+Clone `django-downloadview` repository (adapt to use your own fork):
-`Virtualenv`_).
 
-Execute:
+.. code:: sh
-
-.. code-block:: sh
 
    git clone git@github.com:benoitbryon/django-downloadview.git
    cd django-downloadview/
-   make develop
-
-If you cannot execute the Makefile, read it and adapt the few commands it
-contains to your needs.
 
 
-************
+*************
-The Makefile
+Usual actions
-************
+*************
 
-A :file:`Makefile` is provided to ease development. Use it to:
+The `Makefile` is the reference card for usual actions in development
+environment:
 
-* setup a minimal development environment: ``make develop``
+* Install development toolkit with `pip`_: ``make develop``.
-* run tests: ``make test``
-* build documentation: ``make documentation``
 
-The :file:`Makefile` is intended to be a live reference for the development
+* Run tests with `tox`_: ``make test``.
-environment.
+
+* Build documentation: ``make documentation``. It builds `Sphinx`_
+  documentation in `var/docs/html/index.html`.
+
+* Release project with `zest.releaser`_: ``make release``.
+
+* Cleanup local repository: ``make clean``, ``make distclean`` and
+  ``make maintainer-clean``.
+
+See also ``make help``.
 
 
 *********************
 Demo project included
 *********************
 
-The :doc:`/demo` is part of the tests. Maintain it along with code and
+The `demo` included in project's repository is part of the tests and
-documentation.
+documentation. Maintain it along with code and documentation.
 
 
 .. rubric:: Notes & references
@@ -87,8 +88,7 @@ documentation.
    https://github.com/benoitbryon/django-downloadview/issues
 .. _`rebase`: http://git-scm.com/book/en/Git-Branching-Rebasing
 .. _`merge-based rebase`: http://tech.novapost.fr/psycho-rebasing-en.html
-.. _`Python`: http://python.org
+.. _`pip`: https://pypi.python.org/pypi/pip/
 .. _`tox`: http://tox.testrun.org
-.. _`Virtualenv`: http://virtualenv.org
+.. _`Sphinx`: https://pypi.python.org/pypi/Sphinx/
-.. _`style guide for Sphinx-based documentations`:
+.. _`zest.releaser`: https://pypi.python.org/pypi/zest.releaser/
-   http://documentation-style-guide-sphinx.readthedocs.org/

Makefile

@@ -1,25 +1,53 @@
 # Reference card for usual actions in development environment.
 #
-# For standard installation of hospital as a library, see INSTALL.
+# For standard installation of django-downloadview as a library, see INSTALL.
-# For details about hospital's development environment, see CONTRIBUTING.rst.
+#
+# For details about django-downloadview's development environment, see
+# CONTRIBUTING.rst.
+#
+PIP = pip
+TOX = tox
 
 
+.PHONY: all help develop clean distclean maintainer-clean test documentation sphinx readme demo runserver release
+
+
+# Default target. Does nothing.
+all:
+	@echo "Reference card for usual actions in development environment."
+	@echo "Nothing to do by default."
+	@echo "Try 'make help'."
+
+
+#: help - Display callable targets.
+help:
+	@echo "Reference card for usual actions in development environment."
+	@echo "Here are available targets:"
+	@egrep -o "^#: (.+)" [Mm]akefile  | sed 's/#: /* /'
+
+
+#: develop - Install minimal development utilities such as tox.
 develop:
-	pip install tox zest.releaser
+	$(PIP) install tox
-	pip install -e ./
+	$(PIP) install -e ./
-	pip install -e ./demo/
+	$(PIP) install -e ./demo/
 
 
+#: clean - Basic cleanup, mostly temporary files.
 clean:
 	find . -name "*.pyc" -delete
+	find . -name "__pycache__" -delete
 	find . -name ".noseids" -delete
 
 
+#: distclean - Remove local builds, such as *.egg-info.
 distclean: clean
+	rm -rf *.egg
 	rm -rf *.egg-info
 	rm -rf demo/*.egg-info
 
 
+#: maintainer-clean - Remove almost everything that can be re-generated.
 maintainer-clean: distclean
 	rm -rf bin/
 	rm -rf lib/
@@ -28,23 +56,23 @@ maintainer-clean: distclean
 	rm -rf .tox/
 
 
+#: test - Run full test suite.
 test:
-	tox
+	$(TOX)
-
-
-test-app:
-	tox -e py27
-
-
-test-demo:
-	tox -e demo
 
 
+#: sphinx - Build Sphinx documentation.
 sphinx:
-	tox -e sphinx
+	$(TOX) -e sphinx
 
 
-documentation: sphinx
+#: readme - Build standalone documentation files (README, CONTRIBUTING...).
+readme:
+	$(TOX) -e readme
+
+
+#: documentation - Build full documentation.
+documentation: sphinx readme
 
 
 demo: develop
@@ -61,5 +89,6 @@ runserver: demo
 	demo runserver
 
 
+#: release - Tag and push to PyPI.
 release:
-	fullrelease
+	$(TOX) -e release

docs/Makefile

@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build  # Turn warnings into errors.
+SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = ../var/docs
 

tox.ini

@@ -7,7 +7,7 @@ deps =
     rednose
     coverage
 commands =
-    pip install -e ./
+    pip install ./
     pip install -e demo/
     demo test --nose-verbosity=2 -c etc/nose/base.cfg -c etc/nose/django_downloadview.cfg django_downloadview
     demo test --nose-verbosity=2 demoproject
@@ -29,7 +29,8 @@ deps =
     rednose
     Sphinx
 commands =
-    make --directory=docs clean html doctest
+    pip install ./
+    make --directory=docs SPHINXBUILD="sphinx-build -W" clean html doctest
 whitelist_externals =
     make
 
@@ -40,5 +41,12 @@ deps =
 commands =
     mkdir -p var/docs
     rst2html.py --exit-status=2 README.rst var/docs/README.html
+    rst2html.py --exit-status=2 CONTRIBUTING.rst var/docs/CONTRIBUTING.html
 whitelist_externals =
     mkdir
+
+[testenv:release]
+deps =
+    zest.releaser
+commands =
+    fullrelease