Create sphinx (read-the-docs compatible) docs for Bugwarrior.

MANIFEST.in

@@ -1,3 +1,4 @@
 include bugwarrior/README.rst
 include README.rst
 include LICENSE.txt
+recursive-include docs *.rst

bugwarrior/config.py

@@ -71,8 +71,10 @@ def get_service_password(service, username, oracle=None, interactive=False):
 
 
 def load_example_rc():
-    root = '/'.join(__file__.split('/')[:-1])
-    fname = root + '/README.rst'
+    fname = os.path.join(
+        os.path.dirname(__file__),
+        '../docs/source/configuration.rst'
+    )
     with open(fname, 'r') as f:
         readme = f.read()
     example = readme.split('.. example')[1][4:]

bugwarrior/db.py

@@ -320,7 +320,6 @@ def merge_annotations(remote_issue, local_task):
 
 
 def synchronize(issue_generator, conf):
-
     def _bool_option(section, option, default):
         try:
             return section in conf.sections() and \

docs/generate_service_template.py

@@ -0,0 +1,100 @@
+import inspect
+import os
+import sys
+
+from jinja2 import Template
+
+from bugwarrior.services import Issue
+
+
+def make_table(grid):
+    """ Make a RST-compatible table
+
+    From http://stackoverflow.com/a/12539081
+
+    """
+    cell_width = 2 + max(
+        reduce(
+            lambda x, y: x+y, [[len(item) for item in row] for row in grid], []
+        )
+    )
+    num_cols = len(grid[0])
+    rst = table_div(num_cols, cell_width, 0)
+    header_flag = 1
+    for row in grid:
+        rst = rst + '| ' + '| '.join(
+            [normalize_cell(x, cell_width-1) for x in row]
+        ) + '|\n'
+        rst = rst + table_div(num_cols, cell_width, header_flag)
+        header_flag = 0
+    return rst
+
+
+def table_div(num_cols, col_width, header_flag):
+    if header_flag == 1:
+        return num_cols*('+' + (col_width)*'=') + '+\n'
+    else:
+        return num_cols*('+' + (col_width)*'-') + '+\n'
+
+
+def normalize_cell(string, length):
+    return string + ((length - len(string)) * ' ')
+
+
+def import_by_path(name):
+    m = __import__(name)
+    for n in name.split(".")[1:]:
+        m = getattr(m, n)
+    return m
+
+
+def row_comparator(left_row, right_row):
+    left = left_row[0]
+    right = right_row[0]
+    if left > right:
+        return 1
+    elif right > left or left == 'Field Name':
+        return -1
+    return 0
+
+
+TYPE_NAME_MAP = {
+    'date': 'Date & Time',
+    'numeric': 'Numeric',
+    'string': 'Text (string)',
+    'duration': 'Duration'
+}
+
+
+if __name__ == '__main__':
+    service = sys.argv[1]
+    module = import_by_path(
+        'bugwarrior.services.{service}'.format(service=service)
+    )
+    rows = []
+    for name, obj in inspect.getmembers(module):
+        if inspect.isclass(obj) and issubclass(obj, Issue):
+            for field_name, details in obj.UDAS.items():
+                rows.append(
+                    [
+                        '``%s``' % field_name,
+                        ' '.join(details['label'].split(' ')[1:]),
+                        TYPE_NAME_MAP.get(
+                            details['type'],
+                            '``%s``' % details['type'],
+                        ),
+                    ]
+                )
+
+    rows = sorted(rows, cmp=row_comparator)
+    rows.insert(0, ['Field Name', 'Description', 'Type'])
+
+    filename = os.path.join(os.path.dirname(__file__), 'service_template.html')
+    with open(filename) as template:
+        rendered = Template(template.read()).render({
+            'service_name_humane': service.title(),
+            'service_name': service,
+            'uda_table': make_table(rows)
+        })
+
+    print rendered

docs/service_template.html

@@ -0,0 +1,24 @@
+{{ service_name_humane }}
+=========================
+
+You can import tasks from your {{ service_name_humane }} instance using
+the ``{{ service_name }}`` service name.
+
+Instructions
+------------
+
+Example Service
+---------------
+
+Here's an example of an {{ service_name_humane }} target::
+
+    [my_issue_tracker]
+    service = {{ service_name }}
+
+Service Features
+----------------
+
+Provided UDA Fields
+-------------------
+
+{{ uda_table }}

docs/source/common_configuration.rst

@@ -0,0 +1,138 @@
+How to Configure
+================
+
+First, add a file named named ``.bugwarriorrc`` to your home folder.
+This file must include at least a ``[general]`` section including
+the following option:
+
+* ``targets``: A comma-separated list of *other* section names to use
+  as task sources.
+
+Optional options include:
+
+* ``taskrc``: Specify which TaskRC configuration file to use.  By default,
+  will use the system default (usually ``~/.taskrc``).
+* ``shorten``: Set to ``True`` to shorten links.
+* ``legacy_matching``: Set to ``False`` to instruct Bugwarrior to match
+  issues using only the issue's unique identifiers (rather than matching
+  on description).
+* ``log.level``: Set to one of ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``,
+  ``CRITICAL``, or ``DISABLED`` to control the logging verbosity.  By
+  default, this is set to ``DEBUG``.
+* ``log.file``: Set to the path at which you would like logging messages
+  written.  By default, logging messages will be written to stderr.
+* ``annotation_length``: Import maximally this number of characters
+  of incoming annotations.  Default: 45.
+
+A more-detailed example configuration can be found at :ref:`example_configuration`.
+
+Common Service Configuration Options
+------------------------------------
+
+All services support the following configuration options in addition
+to any specified service features or settings specified in the
+service example:
+
+* ``only_if_assigned``: Only import issues assigned to the specified
+  user.
+* ``also_unassigned``: Same as above, but also create tasks for issues
+  that are not assigned to anybody.
+* ``default_priority``: Assign this priority ('L', 'M', or 'H') to
+  newly-imported issues.
+* ``add_tags``: Add these tags to newly-imported issues.
+* ``description_template``: Build the issue description following this
+  template.  See `Description Templates`_ for more details.
+
+.. _description_templates:
+
+Description Templates
+---------------------
+
+By default, Bugwarrior will import issues with a fairly verbose description
+template looking something like this::
+
+    (BW)Issue#10 - Fix perpetual motion machine .. http://media.giphy.com/media/LldEzRPqyo2Yg/giphy.gif
+
+but depending upon your workflow, the information presented may not be
+useful to you.
+
+To help users build descriptions that suit their needs, all services allow
+one to specify a ``description_template`` configuration option, in which
+one can enter a one-line Jinja template.  The context available includes
+all Taskwarrior fields and all UDAs (see section named 'Provided UDA Fields'
+for each service) defined for the relevant service.
+
+For example, to pull-in github issues assigned to
+`@ralphbean <https://github.com/ralphbean>`_, setting the issue description
+such that it is composed of only the github issue number and title, you could
+create a service entry like this::
+
+    [ralphs_github_account]
+    service = github
+    github.username = ralphbean
+    description_template = {{githubnumber}}: {{githubtitle}}
+
+Password Management
+-------------------
+
+You need not store your password in plain text in your `~/.bugwarriorrc` file; 
+you can enter the following values to control where to gather your password
+from:
+
+* ``password = @oracle:use_keyring``: Retrieve a password from a keyring.
+* ``password = @oracle:ask_password``: Ask for a password at runtime.
+* ``password = @oracle:eval:<command>`` Use the output of <command> as the password.
+
+Hooks
+-----
+
+Use hooks to run commands prior to importing from bugwarrior-pull.
+bugwarrior-pull will run the commands in the order that they are specified
+below.
+
+To use hooks, add a ``[hooks]`` section to your configuration, mapping
+the hook you'd like to use with a comma-separated list of scripts to execute.
+
+::
+
+  [hooks]
+  pre_import = /home/someuser/backup.sh, /home/someuser/sometask.sh
+
+Hook options:
+
+* ``pre_import``: The pre_import hook is invoked after all issues have been pulled
+  from remote sources, but before they are synced to the TW db. If your
+  pre_import script has a non-zero exit code, the ``bugwarrior-pull`` command will
+  exit early.
+
+
+Notifications
+-------------
+
+Add a ``[notifications]`` section to your configuration to receive notifications
+when a bugwarrior pull runs, and when issues are created, updated, or deleted
+by ``bugwarrior-pull``::
+
+  [notifications]
+  notifications = True
+  backend = growlnotify
+  finished_querying_sticky = False
+  task_crud_sticky = True
+
+Backend options:
+
++------------------+------------------+-------------------------+
+| Backend Name     | Operating System | Required Python Modules |
++==================+==================+=========================+
+| ``growlnotify``  | MacOS X          | ``gntp``                |
++------------------+------------------+-------------------------+
+| ``gobject``      | Linux            | ``gobject``             |
++------------------+------------------+-------------------------+
+| ``pynotify``     | Linux            | ``pynotify``            |
++------------------+------------------+-------------------------+
+
+.. note::
+
+   The ``finished_querying_sticky`` and ``task_crud_sticky`` options
+   have no effect if you are using a notification backend other than
+   ``growlnotify``.