From d034c6b67fac1eaeecdaaaa7b7914d663be56aa4 Mon Sep 17 00:00:00 2001
From: Markus Unterwaditzer <markus@unterwaditzer.net>
Date: Mon, 4 Apr 2016 23:24:06 +0200
Subject: [PATCH] Split table of contents into three categories

* Split table of contents into three categories

* Add info about issue tracker and waffle.io

Fix #388
---
 docs/contributing.rst | 33 ++++++++++++++++++++++++++++++---
 docs/index.rst        | 16 ++++++++++++----
 2 files changed, 42 insertions(+), 7 deletions(-)

diff --git a/docs/contributing.rst b/docs/contributing.rst
index 06aba9e..5774257 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -4,8 +4,33 @@ Contributing to this project
 
 **Important:** Please read :doc:`contact` for questions and support requests.
 
+The issue tracker
+=================
+
+We use `GitHub issues <https://github.com/pimutils/vdirsyncer/issues>`_ for
+organizing bug reports and feature requests.
+
+The following `labels <https://github.com/pimutils/vdirsyncer/labels>`_ are of
+interest:
+
+* "Planning" is for issues that are still undecided, but where at least some
+  discussion exists.
+
+* "Blocked" is for issues that can't be worked on at the moment because some
+  other unsolved problem exists. This problem may be a bug in some software
+  dependency, for instance.
+
+* "Ready" contains issues that are ready to work on.
+
+All of those labels are also available as a kanban board on `waffles.io
+<https://waffle.io/pimutils/vdirsyncer>`_. It is really just an alternative
+overview over all issues, but might be easier to comprehend.
+
+Feel free to :doc:`contact <contact>` me or comment on the relevant issues for
+further information.
+
 Reporting bugs
-==============
+--------------
 
 * Make sure your problem isn't already listed in `Known Problems
   <https://vdirsyncer.readthedocs.org/en/stable/problems.html>`_.
@@ -16,7 +41,7 @@ Reporting bugs
 * Use ``--verbosity=DEBUG`` when including output from vdirsyncer.
 
 Suggesting features
-===================
+-------------------
 
 If you're suggesting a feature, keep in mind that vdirsyncer tries not to be a
 full calendar or contacts client, but rather just the piece of software that
@@ -37,7 +62,7 @@ Submitting patches, pull requests
 * Add yourself to ``AUTHORS.rst``, and add a note to ``CHANGELOG.rst`` too.
 
 Running tests, how to set up your development environment
-=========================================================
+---------------------------------------------------------
 
 For many patches, it might suffice to just let Travis run the tests. However,
 Travis is slow, so you might want to run them locally too. For this, set up a
@@ -46,11 +71,13 @@ virtualenv_ and run this inside of it::
     make install-dev  # install vdirsyncer from the repo into the virtualenv
     make install-test  # install test dependencies
     make install-style  # install dependencies for stylechecking
+    make install-docs  # install dependencies for building documentation
 
 Then you can run::
 
     make test  # The normal testsuite
     make style  # Stylechecker
+    make docs  # Build the HTML docs, output is at docs/_build/html/
 
 If you have any questions, feel free to open issues about it.
 
diff --git a/docs/index.rst b/docs/index.rst
index 8bab67f..b2b3ae8 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -14,10 +14,8 @@ know or worry about syncing to a server.
 It aims to be for CalDAV and CardDAV what `OfflineIMAP
 <http://offlineimap.org/>`_ is for IMAP.
 
-Table of Contents
-=================
-
 .. toctree::
+   :caption: Users
    :maxdepth: 1
 
    when
@@ -27,8 +25,18 @@ Table of Contents
    config
    supported
    problems
-   vdir
+
+.. toctree::
+   :caption: Developers
+   :maxdepth: 1
+
    contributing
+   vdir
+
+.. toctree::
+   :caption: General
+   :maxdepth: 1
+
    packaging
    contact
    changelog