diff --git a/.gitignore b/.gitignore index 553b655..9307862 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ # Generated files +/docs/dev-doc/ /build/ *.pyc offlineimap.1 diff --git a/docs/Makefile b/docs/Makefile index 70a99a2..8fd880d 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -7,8 +7,9 @@ HTML_TARGETS = $(patsubst %.rst,%.html,$(SOURCES)) RM = rm RST2HTML=`type rst2html >/dev/null 2>&1 && echo rst2html || echo rst2html.py` RST2MAN=`type rst2man >/dev/null 2>&1 && echo rst2man || echo rst2man.py` +SPHINXBUILD = sphinx-build -all: html +all: html dev-doc html: $(HTML_TARGETS) @@ -21,6 +22,12 @@ offlineimap.1: MANUAL.rst $(RST2MAN) MANUAL.rst offlineimap.1 cp -f offlineimap.1 .. +dev-doc: + $(SPHINXBUILD) -b html -d dev-doc/doctrees dev-doc-src dev-doc/html + clean: $(RM) -f $(HTML_TARGETS) $(RM) -f offlineimap.1 ../offlineimap.1 + $(RM) -rf dev-doc/* + +.PHONY: dev-doc diff --git a/docs/dev-doc-src/conf.py b/docs/dev-doc-src/conf.py new file mode 100644 index 0000000..9269a51 --- /dev/null +++ b/docs/dev-doc-src/conf.py @@ -0,0 +1,200 @@ +# -*- coding: utf-8 -*- +# +# pyDNS documentation build configuration file, created by +# sphinx-quickstart on Tue Feb 2 10:00:47 2010. +# +# 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, 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('../..')) + +from offlineimap import __version__,__author__ +# -- General configuration ----------------------------------------------------- + +# 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.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo'] +autoclass_content = "both" + +# 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' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'OfflineImap' +copyright = u'2002-2010, ' + __author__ + +# 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 = __version__ +# The full version, including alpha/beta/rc tags. +release = __version__ + +# 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 documents that shouldn't be included in the build. +#unused_docs = [] + +# List of directories, relative to source directory, that shouldn't be searched +# for source files. +exclude_trees = [] + +# 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 = False + +# 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 = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +html_theme = 'default' + +# 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 +# " v 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 = ['../html'] + +# 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_use_modindex = False + +# 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, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = '' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'offlineimapdoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'offlineimap.tex', u'OfflineImap Documentation', + u'OfflineImap contributors', '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 + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_use_modindex = True + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/docs/dev-doc-src/index.rst b/docs/dev-doc-src/index.rst new file mode 100644 index 0000000..dff8620 --- /dev/null +++ b/docs/dev-doc-src/index.rst @@ -0,0 +1,82 @@ +.. OfflineImap documentation master file + +.. currentmodule:: offlineimap + +Welcome to :mod:`offlineimaps`'s documentation +=========================================== + +The :mod:`offlineimap` module provides the user interface for synchronization between IMAP servers and MailDirs or between IMAP servers. The homepage containing the source code repository can be found at the `offlineimap wiki `_. + +Within :mod:`offlineimap`, the classes :class:`OfflineImap` provides the high-level functionality. The rest of the classes should usually not needed to be touched by the user. A folder is represented by a :class:`offlineimap.folder.Base.BaseFolder` or any derivative :mod:`offlineimap.folder`. + +.. moduleauthor:: John Goerzen, Sebastian Spaeth + +:License: This module is covered under the GNU GPL v2 (or later). + +This page contains the main API overview of OfflineImap |release|. + +Notmuch can be imported as:: + + from offlineimap import OfflineImap + +More information on specific topics can be found on the following pages: + +.. toctree:: + :maxdepth: 1 + + offlineimap + +:mod:`offlineimap` -- The OfflineImap module +================================================= + +.. automodule:: offlineimap + +.. autoclass:: offlineimap.OfflineImap(cmdline_opts = None) + + .. automethod:: parse_commandline + + .. automethod:: write_pidfile + + .. automethod:: delete_pidfile + + .. automethod:: lock + + .. automethod:: unlock + + .. autoattribute:: ui + + :todo: Document + +:mod:`offlineimap.folder` -- Basic representation of a local or remote Mail folder +--------------------------------------------------------------------------------------------------------- + +.. autoclass:: offlineimap.folder.Base.BaseFolder + :members: + :inherited-members: + +.. .. note:: :meth:`foo` +.. .. attribute:: Database.MODE + + Defines constants that are used as the mode in which to open a database. + + MODE.READ_ONLY + Open the database in read-only mode + + MODE.READ_WRITE + Open the database in read-write mode + + +:exc:`OfflineImapException` -- A Notmuch execution error +------------------------------------------------ +.. autoexception:: offlineimap.OfflineImapException + :members: + + This execption inherits directly from :exc:`Exception` and is raised on errors during the notmuch execution. + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` + diff --git a/docs/dev-doc-src/offlineimap.rst b/docs/dev-doc-src/offlineimap.rst new file mode 100644 index 0000000..f206c11 --- /dev/null +++ b/docs/dev-doc-src/offlineimap.rst @@ -0,0 +1,74 @@ +The offlineimap 'binary' +======================== + +Offlineimap is invoked with the following pattern: `offlineimap [args...]`. + +Where [args...] are as follows: + +Options: + --version show program's version number and exit + -h, --help show this help message and exit + -1 Disable all multithreading operations and use solely a + single-thread sync. This effectively sets the + maxsyncaccounts and all maxconnections configuration + file variables to 1. + -P DIR Sets OfflineIMAP into profile mode. The program will + create DIR (it must not already exist). As it runs, + Python profiling information about each thread is + logged into profiledir. Please note: This option is + present for debugging and optimization only, and + should NOT be used unless you have a specific reason + to do so. It will significantly slow program + performance, may reduce reliability, and can generate + huge amounts of data. This option implies the + singlethreading option (-1). + -a ACCOUNTS Overrides the accounts section in the config file. + Lets you specify a particular account or set of + accounts to sync without having to edit the config + file. You might use this to exclude certain accounts, + or to sync some accounts that you normally prefer not + to. + -c FILE Specifies a configuration file to use in lieu of + ~/.offlineimaprc. + + -d type1,[type2...] Enables debugging for OfflineIMAP. This is useful if + you are trying to track down a malfunction or figure + out what is going on under the hood. I suggest that + you use this with -1 in order to make the results more + sensible. This option requires one or more debugtypes, + separated by commas. These define what exactly will + be debugged, and so far include the options: imap, + thread,maildir or ALL. The imap option will enable + IMAP protocol stream and parsing debugging. Note that + the output may contain passwords, so take care to + remove that from the debugging output before sending + it to anyone else. The maildir option will enable + debugging for certain Maildir operations. + + -l FILE Log to FILE + + -f folder1,[folder2...] + Only sync the specified folders. The 'folder's are the + *untranslated* foldernames. This command-line option + overrides any 'folderfilter' and 'folderincludes' + options in the configuration file. + + -k `[section:]option=value` + Override configuration file option. If"section" is + omitted, it defaults to "general". Any underscores + "_" in the section name are replaced with spaces: + for instance, to override option "autorefresh" in + the "[Account Personal]" section in the config file + one would use "-k Account_Personal:autorefresh=30". + + -o Run only once, ignoring any autorefresh setting in the + configuration file. + -q Run only quick synchronizations. Ignore any flag + updates on IMAP servers. + -u INTERFACE Specifies an alternative user interface to use. This + overrides the default specified in the configuration + file. The UI specified with -u will be forced to be + used, even if checks determine that it is not usable. + Possible interface choices are: Curses.Blinkenlights, + TTY.TTYUI, Noninteractive.Basic, Noninteractive.Quiet, + Machine.MachineUI