Add more info on how the report a bug or contribute (ref ##128).

CONTRIBUTING.md

@@ -1,21 +0,0 @@
-# How To Contribute
-
-sigal is always open for suggestions and contributions by generous developers.
-Here are a few tipps to get you started.
-
-Please:
-
-- Obey [PEP 8] and [PEP 257].
-- *Always* add tests and docs for your code.
-- Add yourself to the AUTHORS file in an alphabetical fashion, and add your
-  name to the license header of the files you modify.
-- Write [good commit messages].
-- Ideally, [squash] your commits, i.e. make your pull requests just one commit.
-
-Thank you for considering to contribute to sigal !
-
-
-[squash]: http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html
-[PEP 8]: http://www.python.org/dev/peps/pep-0008/
-[PEP 257]: http://www.python.org/dev/peps/pep-0257/
-[good commit messages]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

CONTRIBUTING.rst

@@ -0,0 +1,39 @@
+Filing issues
+-------------
+
+If you have an issue with sigal, the first step is to run::
+
+    sigal build -fd -n 1
+
+to get diagnostic information (debug mode, only one core). If you can identify
+an image or video that is causing the issue, you can create a new directory
+containing only this image/video and rerun ``sigal build -fd -n 1``.
+
+Then, put the output into a gist/pastebin, and fill an issue on github.  You
+can also write to the `mailing list`_ or try to get help via the ``#sigal`` IRC
+channel on freenode.
+
+How To Contribute
+-----------------
+
+sigal is always open for suggestions and contributions by generous developers.
+Here are a few tips to get you started.
+
+Please:
+
+- Obey `PEP 8`_ and `PEP 257`_.
+- *Always* add tests and docs for your code.
+- Add yourself to the AUTHORS file in an alphabetical fashion, and add your
+  name to the license header of the files you modify.
+- Write `good commit messages`_.
+- Ideally, squash_ your commits, i.e. make your pull requests just one commit.
+- Use a branch, it will be easier to squash or rebase on upstream's master.
+
+Thank you for considering to contribute to sigal !
+
+
+.. _Mailing list: mailto:sigal@librelist.com
+.. _squash: http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html
+.. _PEP 8: http://www.python.org/dev/peps/pep-0008/
+.. _PEP 257: http://www.python.org/dev/peps/pep-0257/
+.. _good commit messages: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

Makefile

@@ -7,8 +7,7 @@ init:
 	pip install -r requirements.txt
 
 docs:
-	cd docs && make html
+	make -C docs html
-	@echo "\033[95m\n\nBuild successful! View the docs homepage at docs/_build/html/index.html.\n\033[0m"
 
 colorbox:
 	cat $(COLORBOX_PATH)/{base,skeleton,colorbox,style}.css | cssmin > $(COLORBOX_PATH)/style.min.css
@@ -27,4 +26,4 @@ publish:
 	python setup.py sdist upload
 	python setup.py bdist_wheel upload
 
-.PHONY: colorbox galleria
+.PHONY: colorbox galleria docs

docs/contribute.rst

@@ -0,0 +1,38 @@
+=========================
+ Contributing guidelines
+=========================
+
+.. include:: ../CONTRIBUTING.rst
+
+Setting up the development environment
+--------------------------------------
+
+ Using a virtualenv_::
+
+    git clone https://github.com/saimn/sigal.git
+    cd sigal
+    virtualenv venv
+    . venv/activate
+
+Install sigal in development mode::
+
+    pip install -e .
+
+Install additional dependencies for development (Sphinx, ...)::
+
+    pip install -r requirements.txt
+
+Building the docs
+-----------------
+
+- Run ``make docs`` (or ``make html`` in the ``docs/`` directory).
+
+Running the test suite
+----------------------
+
+- Run ``make test`` (or ``py.test``).
+- Run ``make coverage`` to get the coverage report.
+- Using tox_ you can also run the tests on multiple versions of python.
+
+.. _tox: https://testrun.org/tox/
+.. _virtualenv: https://virtualenv.pypa.io/

docs/index.rst

@@ -13,4 +13,5 @@ Documentation
    image_information
    themes
    plugins
+   contribute
    changelog