From dcb91cbf604ae44ec2b0420fd34b8b2840b72594 Mon Sep 17 00:00:00 2001
From: Simon Conseil <contact@saimon.org>
Date: Thu, 4 Sep 2014 22:46:34 +0200
Subject: [PATCH] Add more info on how the report a bug or contribute (ref
 ##128).

---
 CONTRIBUTING.md     | 21 ---------------------
 CONTRIBUTING.rst    | 39 +++++++++++++++++++++++++++++++++++++++
 Makefile            |  5 ++---
 docs/contribute.rst | 38 ++++++++++++++++++++++++++++++++++++++
 docs/index.rst      |  1 +
 5 files changed, 80 insertions(+), 24 deletions(-)
 delete mode 100644 CONTRIBUTING.md
 create mode 100644 CONTRIBUTING.rst
 create mode 100644 docs/contribute.rst

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
deleted file mode 100644
index eba2de3..0000000
--- a/CONTRIBUTING.md
+++ /dev/null
@@ -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
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
new file mode 100644
index 0000000..5b6b4e8
--- /dev/null
+++ b/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
diff --git a/Makefile b/Makefile
index 820ef2f..6290c74 100644
--- a/Makefile
+++ b/Makefile
@@ -7,8 +7,7 @@ init:
 	pip install -r requirements.txt
 
 docs:
-	cd docs && make html
-	@echo "\033[95m\n\nBuild successful! View the docs homepage at docs/_build/html/index.html.\n\033[0m"
+	make -C docs html
 
 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
diff --git a/docs/contribute.rst b/docs/contribute.rst
new file mode 100644
index 0000000..fc122a7
--- /dev/null
+++ b/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/
diff --git a/docs/index.rst b/docs/index.rst
index 15620ce..2f16bc5 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -13,4 +13,5 @@ Documentation
    image_information
    themes
    plugins
+   contribute
    changelog