diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index b4a8212..26d8289 100644 --- a/CONTRIBUTING.rst +++ b/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 -`Virtualenv`_). +Clone `django-downloadview` repository (adapt to use your own fork): -Execute: - -.. code-block:: sh +.. code:: 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`` -* run tests: ``make test`` -* build documentation: ``make documentation`` +* Install development toolkit with `pip`_: ``make develop``. -The :file:`Makefile` is intended to be a live reference for the development -environment. +* Run tests with `tox`_: ``make test``. + +* 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 -documentation. +The `demo` included in project's repository is part of the tests and +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 -.. _`style guide for Sphinx-based documentations`: - http://documentation-style-guide-sphinx.readthedocs.org/ +.. _`Sphinx`: https://pypi.python.org/pypi/Sphinx/ +.. _`zest.releaser`: https://pypi.python.org/pypi/zest.releaser/ diff --git a/Makefile b/Makefile index 29be069..6e4da66 100644 --- a/Makefile +++ b/Makefile @@ -1,25 +1,53 @@ # Reference card for usual actions in development environment. # -# For standard installation of hospital as a library, see INSTALL. -# For details about hospital's development environment, see CONTRIBUTING.rst. +# For standard installation of django-downloadview as a library, see INSTALL. +# +# 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 -e ./ - pip install -e ./demo/ + $(PIP) install tox + $(PIP) install -e ./ + $(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 - - -test-app: - tox -e py27 - - -test-demo: - tox -e demo + $(TOX) +#: 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 diff --git a/docs/Makefile b/docs/Makefile index 50f203f..363b0ef 100644 --- a/docs/Makefile +++ b/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 diff --git a/tox.ini b/tox.ini index e64f108..769309a 100644 --- a/tox.ini +++ b/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