Build documentation via Sphinx.

.gitignore

@@ -32,6 +32,10 @@ nosetests.xml
 # Translations
 *.mo
 
+# Sphinx documentation
+docs/_build/
+docs/html/
+
 # Mr Developer
 .mr.developer.cfg
 .project

MANIFEST.in

@@ -1,3 +1,5 @@
+# https://docs.python.org/2.7/distutils/sourcedist.html#the-manifest-in-template
+graft docs
 include CHANGES.rst
 include LICENSE
 include MANIFEST.in

docs/changelog.rst

@@ -0,0 +1 @@
+.. include:: ../CHANGES.rst

docs/conf.py

@@ -0,0 +1,64 @@
+# -*- coding: utf-8 -*-
+
+from __future__ import (
+    absolute_import,
+    division,
+    print_function,
+    unicode_literals
+)
+
+import os
+import sys
+import time
+
+# Expose package to autodoc.
+sys.path.insert(0, os.path.abspath('..'))
+import maildir_deduplicate
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.todo',
+    'sphinx.ext.viewcode',
+]
+
+master_doc = 'index'
+
+project = "Maildir Deduplicate"
+author = "Kevin Deldycke"
+
+# We use our own copyright template instead of the default as the latter strip
+# HTML content.
+html_show_copyright = False
+copyright = "2010-{}, <a href='http://kevin.deldycke.com'>{}</a>".format(
+    time.strftime('%Y'), author)
+
+version = release = maildir_deduplicate.__version__
+
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+nitpicky = True
+# We need a recent sphinx because of the last update format.
+needs_sphinx = '1.4'
+html_last_updated_fmt = 'YYYY-MM-dd'
+templates_path = ['templates']
+
+# Keep the same ordering as in original source code.
+autodoc_member_order = 'bysource'
+# Include all default flags
+import pdb; pdb.set_trace()  # XXX BREAKPOINT
+
+#autodoc_default_flag [
+#    'members', 'undoc-members', 'private-members', 'special-members']
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
+
+# Use RTD theme both locally and online. Source: https://github.com/snide
+# /sphinx_rtd_theme#using-this-theme-locally-then-building-on-read-the-docs
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+if not on_rtd:
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+htmlhelp_basename = project

docs/development.rst

@@ -0,0 +1,211 @@
+Development
+===========
+
+
+Philosophy
+----------
+
+1. First create something that work (to provide business value).
+2. Then something that's beautiful (to lower maintenance costs).
+3. Finally works on performance (to avoid wasting time on premature
+   optimizations).
+
+
+Build status
+------------
+
+==============  ==================  ===================
+Branch          |master-branch|__   |develop-branch|__
+==============  ==================  ===================
+Unittests       |build-stable|      |build-dev|
+Coverage        |coverage-stable|   |coverage-dev|
+Quality         |quality-stable|    |quality-dev|
+Dependencies    |deps-stable|       |deps-dev|
+Documentation   |docs-stable|       |docs-dev|
+==============  ==================  ===================
+
+.. |master-branch| replace::
+   ``master``
+__ https://github.com/kdeldycke/maildir-deduplicate/tree/master
+.. |develop-branch| replace::
+   ``develop``
+__ https://github.com/kdeldycke/maildir-deduplicate/tree/develop
+
+.. |build-stable| image:: https://img.shields.io/travis/kdeldycke/maildir-deduplicate/master.svg?style=flat
+    :target: https://travis-ci.org/kdeldycke/maildir-deduplicate
+    :alt: Unit-tests status
+.. |build-dev| image:: https://img.shields.io/travis/kdeldycke/maildir-deduplicate/master.svg?style=flat
+    :target: https://travis-ci.org/kdeldycke/maildir-deduplicate
+    :alt: Unit-tests status
+
+.. |coverage-stable| image:: https://codecov.io/github/kdeldycke/maildir-deduplicate/coverage.svg?branch=master
+    :target: https://codecov.io/gh/kdeldycke/maildir-deduplicate/branch/master
+    :alt: Coverage Status
+.. |coverage-dev| image:: https://codecov.io/github/kdeldycke/maildir-deduplicate/coverage.svg?branch=develop
+    :target: https://codecov.io/gh/kdeldycke/maildir-deduplicate/branch/develop
+    :alt: Coverage Status
+
+.. |quality-stable| image:: https://img.shields.io/scrutinizer/g/kdeldycke/maildir-deduplicate.svg?style=flat
+    :target: https://scrutinizer-ci.com/g/kdeldycke/maildir-deduplicate/?branch=master
+    :alt: Code Quality
+.. |quality-dev| image:: https://img.shields.io/scrutinizer/g/kdeldycke/maildir-deduplicate.svg?style=flat
+    :target: https://scrutinizer-ci.com/g/kdeldycke/maildir-deduplicate/?branch=develop
+    :alt: Code Quality
+
+.. |deps-stable| image:: https://img.shields.io/requires/github/kdeldycke/maildir-deduplicate/master.svg?style=flat
+    :target: https://requires.io/github/kdeldycke/maildir-deduplicate/requirements/?branch=master
+    :alt: Requirements freshness
+.. |deps-dev| image:: https://img.shields.io/requires/github/kdeldycke/maildir-deduplicate/develop.svg?style=flat
+    :target: https://requires.io/github/kdeldycke/maildir-deduplicate/requirements/?branch=develop
+    :alt: Requirements freshness
+
+.. |docs-stable| image:: https://readthedocs.org/projects/maildir-deduplicate/badge/?version=stable
+    :target: http://maildir-deduplicate.readthedocs.io/en/stable/
+    :alt: Documentation Status
+.. |docs-dev| image:: https://readthedocs.org/projects/maildir-deduplicate/badge/?version=develop
+    :target: http://maildir-deduplicate.readthedocs.io/en/develop/
+    :alt: Documentation Status
+
+
+Setup a development environment
+-------------------------------
+
+Check out latest development branch:
+
+.. code-block:: bash
+
+    $ git clone git@github.com:kdeldycke/maildir-deduplicate.git
+    $ cd ./maildir-deduplicate
+    $ git checkout develop
+
+Install package in editable mode with all development dependencies:
+
+.. code-block:: bash
+
+    $ pip install -e .[develop]
+
+Now you're ready to hack and abuse git!
+
+
+Unit-tests
+----------
+
+Install test dependencies and run unit-tests:
+
+.. code-block:: bash
+
+    $ pip install -e .[tests]
+    $ nosetests
+
+
+Coding style
+------------
+
+Run `isort <https://github.com/timothycrosley/isort>`_ utility to sort Python
+imports:
+
+.. code-block:: bash
+
+    $ pip install -e .[develop]
+    $ isort --apply
+
+Then run `pycodestyle <https://pycodestyle.readthedocs.io>`_ and `Pylint
+<http://docs.pylint.org>`_ code style checks:
+
+.. code-block:: bash
+
+    $ pip install -e .[tests]
+    $ pycodestyle maildir_deduplicate
+    $ pylint --rcfile=setup.cfg maildir_deduplicate
+
+
+Build documentation
+-------------------
+
+The documentation you're currently reading can be built locally with `Sphinx
+<http://www.sphinx-doc.org>`_:
+
+.. code-block:: bash
+
+    $ pip install -e .[docs]
+    $ sphinx-apidoc -f -o ./docs .
+    $ sphinx-build -b html ./docs ./docs/html
+
+
+Release process
+---------------
+
+Start from the ``develop`` branch:
+
+.. code-block:: bash
+
+    $ git clone git@github.com:kdeldycke/maildir-deduplicate.git
+    $ cd ./maildir-deduplicate
+    $ git checkout develop
+
+Install development dependencies:
+
+.. code-block:: bash
+
+    $ pip install -e .[develop]
+
+Revision should already be set to the next version, so we just need to set the
+released date in the changelog:
+
+.. code-block:: bash
+
+    $ vi ./CHANGES.rst
+
+Create a release commit, tag it and merge it back to ``master`` branch:
+
+.. code-block:: bash
+
+    $ git add ./maildir_deduplicate/__init__.py ./CHANGES.rst
+    $ git commit -m "Release vX.Y.Z"
+    $ git tag "vX.Y.Z"
+    $ git push
+    $ git push --tags
+    $ git checkout master
+    $ git pull
+    $ git merge "vX.Y.Z"
+    $ git push
+
+Push packaging to the `test cheeseshop
+<https://wiki.python.org/moin/TestPyPI>`_:
+
+.. code-block:: bash
+
+    $ python ./setup.py register -r testpypi
+    $ python ./setup.py clean
+    $ rm -rf ./build ./dist
+    $ python ./setup.py sdist bdist_egg bdist_wheel upload -r testpypi
+
+Publish packaging to `PyPi <https://pypi.python.org>`_:
+
+.. code-block:: bash
+
+    $ python ./setup.py register -r pypi
+    $ python ./setup.py clean
+    $ rm -rf ./build ./dist
+    $ python ./setup.py sdist bdist_egg bdist_wheel upload -r pypi
+
+Update revision with `bumpversion <https://github.com/peritus/bumpversion>`_
+and set it back to development state by increasing the ``patch`` level.
+
+.. code-block:: bash
+
+    $ git checkout develop
+    $ bumpversion --verbose patch
+    $ git add ./maildir_deduplicate/__init__.py ./CHANGES.rst
+    $ git commit -m "Post release version bump."
+    $ git push
+
+Now if the next revision is no longer bug-fix only, bump the ``minor``
+revision level instead:
+
+.. code-block:: bash
+
+    $ bumpversion --verbose minor
+    $ git add ./maildir_deduplicate/__init__.py ./CHANGES.rst
+    $ git commit -m "Next release no longer bug-fix only. Bump revision."
+    $ git push

docs/index.rst

@@ -0,0 +1,19 @@
+.. include:: ../README.rst
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   readme
+   maildir_deduplicate
+   development
+   changelog
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/maildir_deduplicate.rst

@@ -0,0 +1,37 @@
+maildir_deduplicate package
+===========================
+
+Subpackages
+-----------
+
+.. toctree::
+
+    maildir_deduplicate.tests
+
+Submodules
+----------
+
+maildir_deduplicate.cli module
+------------------------------
+
+.. automodule:: maildir_deduplicate.cli
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+maildir_deduplicate.deduplicate module
+--------------------------------------
+
+.. automodule:: maildir_deduplicate.deduplicate
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: maildir_deduplicate
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/maildir_deduplicate.tests.rst

@@ -0,0 +1,30 @@
+maildir_deduplicate.tests package
+=================================
+
+Submodules
+----------
+
+maildir_deduplicate.tests.test_cli module
+-----------------------------------------
+
+.. automodule:: maildir_deduplicate.tests.test_cli
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+maildir_deduplicate.tests.test_deduplicate module
+-------------------------------------------------
+
+.. automodule:: maildir_deduplicate.tests.test_deduplicate
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: maildir_deduplicate.tests
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/modules.rst

@@ -0,0 +1,8 @@
+maildir-deduplicate
+===================
+
+.. toctree::
+   :maxdepth: 4
+
+   maildir_deduplicate
+   setup

docs/setup.rst

@@ -0,0 +1,7 @@
+setup module
+============
+
+.. automodule:: setup
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/templates/footer.html

@@ -0,0 +1,8 @@
+{% extends "!footer.html" %}
+{% block extrafooter %}
+    <div role="contentinfo">
+        <p>
+            {% trans copyright=copyright %}&copy; Copyright {{ copyright }}.{% endtrans %}
+        </p>
+    </div>
+{% endblock %}

setup.py

@@ -34,6 +34,9 @@ DEPENDENCIES = [
 EXTRA_DEPENDENCIES = {
     # Extra dependencies are made available through the
     # `$ pip install .[keyword]` command.
+    'docs': [
+        'sphinx >= 1.4',
+        'sphinx_rtd_theme'],
     'tests': [
         'nose',
         'coverage',