Merge leap_mail into unified bitmask repo

18 files changed, 1190 insertions, 0 deletions

diff --git a/mail/docs/Makefile b/mail/docs/Makefile
new file mode 100644
index 00000000..388b6c65
--- /dev/null
+++ b/mail/docs/Makefile
@@ -0,0 +1,179 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/leapmail.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/leapmail.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/leapmail"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/leapmail"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+build_rtd:
+	curl -X POST http://readthedocs.org/build/leapmail
diff --git a/mail/docs/api/leap.mail.adaptors.rst b/mail/docs/api/leap.mail.adaptors.rst
new file mode 100644
index 00000000..472cadef
--- /dev/null
+++ b/mail/docs/api/leap.mail.adaptors.rst
@@ -0,0 +1,43 @@
+mail.adaptors package
+=====================
+
+.. automodule:: leap.mail.adaptors
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Subpackages
+-----------
+
+.. toctree::
+
+    leap.mail.adaptors.tests
+
+Submodules
+----------
+
+mail.adaptors.models module
+---------------------------
+
+.. automodule:: leap.mail.adaptors.models
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+mail.adaptors.soledad module
+----------------------------
+
+.. automodule:: leap.mail.adaptors.soledad
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+mail.adaptors.soledad_indexes module
+------------------------------------
+
+.. automodule:: leap.mail.adaptors.soledad_indexes
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
diff --git a/mail/docs/api/leap.mail.adaptors.tests.rst b/mail/docs/api/leap.mail.adaptors.tests.rst
new file mode 100644
index 00000000..2ae76e8a
--- /dev/null
+++ b/mail/docs/api/leap.mail.adaptors.tests.rst
@@ -0,0 +1,28 @@
+mail.adaptors.tests package
+===========================
+
+.. automodule:: leap.mail.adaptors.tests
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Submodules
+----------
+
+mail.adaptors.tests.test_models module
+--------------------------------------
+
+.. automodule:: leap.mail.adaptors.tests.test_models
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+mail.adaptors.tests.test_soledad_adaptor module
+-----------------------------------------------
+
+.. automodule:: leap.mail.adaptors.tests.test_soledad_adaptor
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
diff --git a/mail/docs/api/leap.mail.imap.rst b/mail/docs/api/leap.mail.imap.rst
new file mode 100644
index 00000000..bfaa3fd7
--- /dev/null
+++ b/mail/docs/api/leap.mail.imap.rst
@@ -0,0 +1,52 @@
+leap.mail.imap package
+=======================
+
+.. automodule:: leap.mail.imap
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Subpackages
+-----------
+
+.. toctree::
+
+    leap.mail.imap.service
+    leap.mail.imap.tests
+
+Submodules
+----------
+
+leap.mail.imap.account module
+------------------------------
+
+.. automodule:: leap.mail.imap.account
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+leap.mail.imap.mailbox module
+------------------------------
+
+.. automodule:: leap.mail.imap.mailbox
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+leap.mail.imap.messages module
+------------------------------
+
+.. automodule:: leap.mail.imap.messages
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+leap.mail.imap.server module
+-----------------------------
+
+.. automodule:: leap.mail.imap.server
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
diff --git a/mail/docs/api/leap.mail.imap.service.rst b/mail/docs/api/leap.mail.imap.service.rst
new file mode 100644
index 00000000..2f3ed4bb
--- /dev/null
+++ b/mail/docs/api/leap.mail.imap.service.rst
@@ -0,0 +1,9 @@
+leap.mail.imap.service package
+===============================
+
+.. automodule:: leap.mail.imap.service
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
diff --git a/mail/docs/api/leap.mail.incoming.rst b/mail/docs/api/leap.mail.incoming.rst
new file mode 100644
index 00000000..4bd16141
--- /dev/null
+++ b/mail/docs/api/leap.mail.incoming.rst
@@ -0,0 +1,20 @@
+leap.mail.incoming package
+==========================
+
+.. automodule:: leap.mail.incoming
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Submodules
+----------
+
+leap.mail.incoming.service module
+----------------------------------
+
+.. automodule:: leap.mail.incoming.service
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
diff --git a/mail/docs/api/leap.mail.outgoing.rst b/mail/docs/api/leap.mail.outgoing.rst
new file mode 100644
index 00000000..af8c1734
--- /dev/null
+++ b/mail/docs/api/leap.mail.outgoing.rst
@@ -0,0 +1,21 @@
+leap.mail.outgoing package
+==========================
+
+.. automodule:: leap.mail.outgoing
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Submodules
+----------
+
+mail.outgoing.service module
+----------------------------
+
+.. automodule:: leap.mail.outgoing.service
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
diff --git a/mail/docs/api/leap.mail.plugins.rst b/mail/docs/api/leap.mail.plugins.rst
new file mode 100644
index 00000000..7a5d6b4d
--- /dev/null
+++ b/mail/docs/api/leap.mail.plugins.rst
@@ -0,0 +1,20 @@
+leap.mail.plugins package
+==========================
+
+.. automodule:: leap.mail.plugins
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Submodules
+----------
+
+leap.mail.plugins.soledad_sync_hooks module
+-------------------------------------------
+
+.. automodule:: leap.mail.plugins.soledad_sync_hooks
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
diff --git a/mail/docs/api/leap.mail.rst b/mail/docs/api/leap.mail.rst
new file mode 100644
index 00000000..686e648e
--- /dev/null
+++ b/mail/docs/api/leap.mail.rst
@@ -0,0 +1,105 @@
+leap.mail package
+=================
+
+.. automodule:: leap.mail
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Subpackages
+-----------
+
+.. toctree::
+
+    leap.mail.adaptors
+    leap.mail.imap
+    leap.mail.incoming
+    leap.mail.outgoing
+    leap.mail.plugins
+    leap.mail.smtp
+    leap.mail.tests
+
+Submodules
+----------
+
+leap.mail.constants module
+---------------------------
+
+.. automodule:: leap.mail.constants
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+leap.mail.decorators module
+---------------------------
+
+.. automodule:: leap.mail.decorators
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+leap.mail.interfaces module
+----------------------------
+
+.. automodule:: leap.mail.interfaces
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+leap.mail.load_tests module
+----------------------------
+
+.. automodule:: leap.mail.load_tests
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+leap.mail.mail module
+---------------------
+
+.. automodule:: leap.mail.mail
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+leap.mail.mailbox_indexer module
+---------------------------------
+
+.. automodule:: leap.mail.mailbox_indexer
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+leap.mail.size module
+----------------------
+
+.. automodule:: leap.mail.size
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+leap.mail.sync_hooks module
+----------------------------
+
+.. automodule:: leap.mail.sync_hooks
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+leap.mail.utils module
+-----------------------
+
+.. automodule:: leap.mail.utils
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+leap.mail.walk module
+----------------------
+
+.. automodule:: leap.mail.walk
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
diff --git a/mail/docs/api/leap.mail.smtp.rst b/mail/docs/api/leap.mail.smtp.rst
new file mode 100644
index 00000000..f35d3f9d
--- /dev/null
+++ b/mail/docs/api/leap.mail.smtp.rst
@@ -0,0 +1,19 @@
+leap.mail.smtp package
+=======================
+
+.. automodule:: leap.mail.smtp
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Submodules
+----------
+
+leap.mail.smtp.gateway module
+-----------------------------
+
+.. automodule:: leap.mail.smtp.gateway
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
diff --git a/mail/docs/api/modules.rst b/mail/docs/api/modules.rst
new file mode 100644
index 00000000..78277797
--- /dev/null
+++ b/mail/docs/api/modules.rst
@@ -0,0 +1,7 @@
+mail
+====
+
+.. toctree::
+   :maxdepth: 4
+
+   mail
diff --git a/mail/docs/conf.py b/mail/docs/conf.py
new file mode 100644
index 00000000..746f57cf
--- /dev/null
+++ b/mail/docs/conf.py
@@ -0,0 +1,341 @@
+# -*- coding: utf-8 -*-
+#
+# leap.mail documentation build configuration file, created by
+# sphinx-quickstart on Mon Aug 25 19:19:48 2014.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys
+import os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('../src'))
+#sys.path.insert(0, os.path.abspath('../src/leap'))
+#sys.path.insert(0, os.path.abspath('../src/leap/mail'))
+#sys.path.insert(0, os.path.abspath('../../leap_common/src/leap/common'))
+#sys.path.insert(0, os.path.abspath('../../soledad/client/src/leap/soledad/client'))
+
+VENV_PATH = os.environ.get('VIRTUAL_ENV')
+if VENV_PATH:
+    sys.path.insert(0, os.path.abspath(VENV_PATH + 'lib/python2.7/site-packages'))
+
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.todo',
+    'sphinx.ext.coverage',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'leap.mail'
+copyright = u'2014-2015, The LEAP Encryption Access Project'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '0.4.0rc2'
+# The full version, including alpha/beta/rc tags.
+release = '0.4.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'alabaster'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'leapmaildoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+  ('index', 'leapmail.tex', u'leap.mail Documentation',
+   u'Kali Kaneko', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'leapmail', u'leap.mail Documentation',
+     [u'Kali Kaneko'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  ('index', 'leapmail', u'leap.mail Documentation',
+   u'Kali Kaneko', 'leapmail', 'One line description of project.',
+   'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False
+
+
+# -- Options for Epub output ----------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = u'leap.mail'
+epub_author = u'Kali Kaneko'
+epub_publisher = u'Kali Kaneko'
+epub_copyright = u'2014, Kali Kaneko'
+
+# The basename for the epub file. It defaults to the project name.
+#epub_basename = u'leap.mail'
+
+# The HTML theme for the epub output. Since the default themes are not optimized
+# for small screen space, using the same theme for HTML and epub output is
+# usually not wise. This defaults to 'epub', a theme designed to save visual
+# space.
+#epub_theme = 'epub'
+
+# The language of the text. It defaults to the language option
+# or en if the language is not set.
+#epub_language = ''
+
+# The scheme of the identifier. Typical schemes are ISBN or URL.
+#epub_scheme = ''
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#epub_identifier = ''
+
+# A unique identification for the text.
+#epub_uid = ''
+
+# A tuple containing the cover image and cover page html template filenames.
+#epub_cover = ()
+
+# A sequence of (type, uri, title) tuples for the guide element of content.opf.
+#epub_guide = ()
+
+# HTML files that should be inserted before the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_pre_files = []
+
+# HTML files shat should be inserted after the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_post_files = []
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ['search.html']
+
+# The depth of the table of contents in toc.ncx.
+#epub_tocdepth = 3
+
+# Allow duplicate toc entries.
+#epub_tocdup = True
+
+# Choose between 'default' and 'includehidden'.
+#epub_tocscope = 'default'
+
+# Fix unsupported image types using the PIL.
+#epub_fix_images = False
+
+# Scale large images.
+#epub_max_image_width = 0
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#epub_show_urls = 'inline'
+
+# If false, no index is generated.
+#epub_use_index = True
diff --git a/mail/docs/git-commit-message.txt b/mail/docs/git-commit-message.txt
new file mode 100644
index 00000000..1b28baf2
--- /dev/null
+++ b/mail/docs/git-commit-message.txt
@@ -0,0 +1,8 @@
+[bug|feature|docs|pkg]
+
+...
+
+Resolves: #XXX
+Related: #XXX
+Documentation: #XXX
+Releases: XXX 
diff --git a/mail/docs/hacking.rst b/mail/docs/hacking.rst
new file mode 100644
index 00000000..6c49c211
--- /dev/null
+++ b/mail/docs/hacking.rst
@@ -0,0 +1,195 @@
+.. _hacking:
+
+========
+Hacking 
+========
+
+Some hints oriented to `leap.mail` hackers. These notes are mostly related to
+the imap server, although they probably will be useful for other pieces too.
+
+Don't panic! Just manhole into it
+=================================
+
+If you want to inspect the objects living in your application memory, in
+realtime, you can manhole into it.
+
+First of all, check that the modules ``PyCrypto`` and ``pyasn1`` are installed
+into your system, they are needed for it to work.
+
+You just have to pass the ``LEAP_MAIL_MANHOLE=1`` enviroment variable while
+launching the client::
+
+  LEAP_MAIL_MANHOLE=1 bitmask --debug
+
+And then you can ssh into your application! (password is "leap")::
+
+  ssh boss@localhost -p 2222
+
+Did I mention how *awesome* twisted is?? ``:)``
+
+
+Profiling
+=========
+If using ``twistd`` to launch the server, you can use twisted profiling
+capabities::
+
+  LEAP_MAIL_CONFIG=~/.leapmailrc twistd --profile=/tmp/mail-profiling -n -y imap-server.tac
+
+``--profiler`` option allows you to select different profilers (default is
+"hotshot").
+
+You can also do profiling when using the ``bitmask`` client. Enable the
+``LEAP_PROFILE_IMAPCMD`` environment flag to get profiling of certain IMAP
+commands::
+
+ LEAP_PROFILE_IMAPCMD=1 bitmask --debug
+
+Offline mode
+============
+
+The client has an ``--offline`` flag that will make the Mail services (imap,
+currently) not try to sync with remote replicas. Very useful during development,
+although you need to login with the remote server at least once before being
+able to use it.
+
+Mutt config
+===========
+
+You cannot live without mutt? You're lucky! Use the following minimal config
+with the imap service::
+
+ set folder="imap://user@provider@localhost:1984"
+ set spoolfile="imap://user@provider@localhost:1984/INBOX"
+ set ssl_starttls = no
+ set ssl_force_tls = no
+ set imap_pass=MAHSIKRET
+
+
+Running the service with twistd
+===============================
+
+In order to run the mail service (currently, the imap server only), you will
+need a config with this info::
+
+  [leap_mail]
+  userid = "user@provider"
+  uuid = "deadbeefdeadabad"
+  passwd = "foobar" # Optional
+
+In the ``LEAP_MAIL_CONFIG`` enviroment variable. If you do not specify a password
+parameter, you'll be prompted for it.
+
+In order to get the user uid (uuid), look into the
+``~/.config/leap/leap-backend.conf`` file after you have logged in into your
+provider at least once.
+
+Run the twisted service::
+
+  LEAP_MAIL_CONFIG=~/.leapmailrc twistd -n -y imap-server.tac
+
+Now you can telnet into your local IMAP server and read your mail like a real
+programmer™::
+
+  % telnet localhost 1984
+  Trying 127.0.0.1...
+  Connected to localhost.
+  Escape character is '^]'.
+  * OK [CAPABILITY IMAP4rev1 LITERAL+ IDLE NAMESPACE] Twisted IMAP4rev1 Ready
+  tag LOGIN me@myprovider.net mahsikret
+  tag OK LOGIN succeeded
+  tag SELECT Inbox
+  * 2 EXISTS
+  * 1 RECENT
+  * FLAGS (\Seen \Answered \Flagged \Deleted \Draft \Recent List)
+  * OK [UIDVALIDITY 1410453885932] UIDs valid
+  tag OK [READ-WRITE] SELECT successful
+  ^]
+  telnet> Connection closed.
+
+
+Although you probably prefer to use ``offlineimap`` for tests:: 
+
+  offlineimap -c LEAPofflineimapRC-tests
+
+
+Minimal offlineimap configuration
+---------------------------------
+
+You can use this as a sample offlineimap config file::
+
+  [general]
+  accounts = leap-local
+
+  [Account leap-local]
+  localrepository = LocalLeap
+  remoterepository = RemoteLeap
+
+  [Repository LocalLeap]
+  type = Maildir
+  localfolders = ~/LEAPMail/Mail
+
+  [Repository RemoteLeap]
+  type = IMAP
+  ssl = no
+  remotehost = localhost
+  remoteport = 1984
+  remoteuser = user
+  remotepass = pass
+
+Testing utilities
+-----------------
+There are a bunch of utilities to test IMAP delivery in ``imap/tests`` folder.
+If looking for a quick way of inspecting mailboxes, have a look at ``getmail``::
+
+ ./getmail me@testprovider.net mahsikret
+ 1. Drafts
+ 2. INBOX
+ 3. Trash
+ Which mailbox? [1] 2
+ 1 Subject: this is the time of the revolution
+ 2 Subject: ignore me
+
+ Which message? [1] (Q quits) 1
+ 1 X-Leap-Provenance: Thu, 11 Sep 2014 16:52:11 -0000; pubkey="C1F8DE10BD151F99"
+ Received: from mx1.testprovider.net(mx1.testprovider.net [198.197.196.195])
+ (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits))
+ (Client CN "*.foobar.net", Issuer "Gandi Standard SSL CA" (not verified))
+ by blackhole (Postfix) with ESMTPS id DEADBEEF
+ for <me@testprovider.net>; Thu, 11 Sep 2014 16:52:10 +0000 (UTC)
+ Delivered-To: 926d4915cfd42b6d96d38660c04613af@testprovider.net
+ Message-Id: <20140911165205.GB8054@samsara>
+ From: Kali <kali@leap.se>
+ 
+ (snip)
+
+IMAP Message Rendering Regressions
+----------------------------------
+
+For testing the IMAP server implementation, there is a litte regressions script
+that needs some manual work from your side.
+
+First of all, you need an already initialized account. Which for now basically
+means you have created a new account with a provider that offers the Encrypted
+Mail Service, using the Bitmask Client wizard. Then you need to log in with that
+account, and let it generate the secrets and sync with the remote for a first
+time. After this you can run the twistd server locally and offline.
+
+From the ``leap.mail.imap.tests`` folder, and with an already initialized server
+running::
+
+  ./regressions_mime_struct user@provider pass path_to_samples/
+
+You can find several message samples in the ``leap/mail/tests`` folder.
+ 
+
+Debugging IMAP commands
+=======================
+
+Use ``ngrep`` to obtain logs of the commands::
+
+  sudo ngrep -d lo -W byline port 1984
+
+To get verbose output from thunderbird/icedove, set the following environment
+variable::
+
+  NSPR_LOG_MODULES="imap:5" icedove
diff --git a/mail/docs/index.rst b/mail/docs/index.rst
new file mode 100644
index 00000000..a2133f48
--- /dev/null
+++ b/mail/docs/index.rst
@@ -0,0 +1,96 @@
+.. leap.mail documentation master file, created by
+   sphinx-quickstart on Mon Aug 25 19:19:48 2014.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+leap.mail
+=========
+
+*decentralized and secure mail delivery and synchronization*
+
+This is the documentation for the ``leap.mail`` module. It is a `twisted`_
+package that allows to receive, process, send and access existing messages using
+the `LEAP`_ platform.
+
+One way to use this library is to let it launch two standard mail services,
+``smtp`` and ``imap``, that run as local proxies and interact with a remote
+``LEAP`` provider that offers *a soledad syncronization endpoint* and receives 
+the outgoing email. This is what `Bitmask`_ client does.
+
+From the release 0.4.0 on, it's also possible to use a protocol-agnostic email
+public API, so that third party mail clients can manipulate the data layer. This
+is what the awesome MUA in the `Pixelated`_ project is using.
+
+.. _`twisted`: https://twistedmatrix.com/trac/
+.. _`LEAP`: https://leap.se/en/docs
+.. _`Bitmask`: https://bitmask.net/en/features#email
+.. _`Pixelated`: https://pixelated-project.org/
+
+How does this all work?
+-----------------------
+
+All the underlying data storage and sync is handled by a library called
+`soledad`_, which handles encryption, storage and sync. Based on `u1db`_,
+documents are stored locally as local ``sqlcipher`` tables, and syncs against
+the soledad sync service in the provider.
+
+OpenPGP key generation and keyring management are handled by another leap
+python library: `keymanager`_.
+
+See :ref:`the life cycle of a leap email <mail_journey>` for an overview of the life cycle
+of an email through ``LEAP`` providers.
+
+.. _`Soledad`: https://leap.se/en/docs/design/soledad
+.. _`u1db`: https://en.wikipedia.org/wiki/U1DB
+.. _`keymanager`: https://github.com/leapcode/keymanager/
+
+
+Data model
+----------
+.. TODO clear document types documentation.
+
+The data model at the present moment consists of several *document types* that split email into
+different documents that are stored in ``Soledad``. The idea behind this is to
+keep clear the separation between *mutable* and *inmutable* parts, and still being able to
+reconstruct arbitrarily nested email structures easily.
+
+Documentation index
+===================
+
+..
+.. Contents:
+.. toctree::
+   :maxdepth: 2
+
+   hacking
+
+..   intro
+..   tutorial
+
+
+API documentation
+-----------------
+
+If you were looking for the documentation of the ``leap.mail`` module, you will
+find it here.
+
+Of special interest is the `public mail api`_, which should remain relatively
+stable across the next few releases.
+
+.. _`public mail api`: api/mail.html#module-mail
+
+
+.. toctree::
+   :maxdepth: 2
+
+   api/leap.mail
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
diff --git a/mail/docs/mail_journey.rst b/mail/docs/mail_journey.rst
new file mode 100644
index 00000000..7e64f186
--- /dev/null
+++ b/mail/docs/mail_journey.rst
@@ -0,0 +1,40 @@
+.. _mail_journey:
+
+The life cycle of a LEAP Email
+==============================
+The following are just some notes to facilitate the understanding of the
+leap.mail internals to developers and collaborators.
+
+Server-side: receiving mail from the outside world
+--------------------------------------------------
+
+1. the mx server receives an email, it gets through all the postfix validation and it's written into disk
+2. ``leap_mx`` gets that write in disk notification and encrypts the incoming mail to its intended recipient's pubkey
+3. that encrypted blob gets written into couchdb in a way soledad will catch it in the next sync
+
+
+Client-side: fetching and processing incoming email
+---------------------------------------------------
+you have an imap and an smtp local server. For IMAP:
+
+1. soledad syncs
+2. **fetch** module sees if there's new encrypted mail for the current user from leap_mx
+3. if there is, the mail is decrypted using the user private key, and splitted
+   into several parts according to the internal mail data model (separating
+   mutable and inmutable email parts). Those documents it encrypts it properly
+   like other soledad documents and deletes the pubkey encrypted doc
+4. desktop client is notified that there are N new mails 
+5. when a MUA connects to the **imap** local server, the different documents are glued
+   together and presented as response to the different imap commands.
+
+
+Client side: sending email
+--------------------------
+
+1. you write an email to a recipient and hit send
+2. the **smtp** local server gets that mail, it checks from whom it is and to whom it is for
+3. it signs the mail with the ``From:``'s privkey
+4. it retrieves ``To:``'s pubkey with the keymanager and if it finds it encrypts the mail to him/her
+5. if it didn't find it and you don't have your client configured to "always encrypt", it goes out with just the signature
+6. else, it fails out complaining about this conflict
+7. that mail gets relayed to the provider's **smtp** server
diff --git a/mail/docs/recreate_apidocs.sh b/mail/docs/recreate_apidocs.sh
new file mode 100755
index 00000000..9a79d091
--- /dev/null
+++ b/mail/docs/recreate_apidocs.sh
@@ -0,0 +1,4 @@
+#!/bin/sh
+# Watchout! this will need much manual touches
+# to the generated apidocs. Mainly: s/mail/leap.mail/g
+sphinx-apidoc -M -o api ../src/leap/mail
diff --git a/mail/docs/tutorial.rst b/mail/docs/tutorial.rst
new file mode 100644
index 00000000..5cf7d026
--- /dev/null
+++ b/mail/docs/tutorial.rst
@@ -0,0 +1,3 @@
+Tutorial
+========
+`leap.mail` tutorial