Improve the developer API documentation

Improve the code documentation (still much more to do) and also add some
more meat to the structure of the developer documentation.

Signed-off-by: Sebastian Spaeth <Sebastian@SSpaeth.de>
Signed-off-by: Nicolas Sebrecht <nicolas.s-dev@laposte.net>
This commit is contained in:
Sebastian Spaeth 2011-05-02 17:11:40 +02:00 committed by Nicolas Sebrecht
parent e9a7afda6d
commit 6add201436
8 changed files with 153 additions and 45 deletions

View File

@ -122,7 +122,7 @@ html_theme = 'default'
# Add any paths that contain custom static files (such as style sheets) here, # 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, # relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css". # so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['../html'] #html_static_path = ['html']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format. # using the given strftime format.
@ -160,7 +160,7 @@ html_use_modindex = False
#html_file_suffix = '' #html_file_suffix = ''
# Output file base name for HTML help builder. # Output file base name for HTML help builder.
htmlhelp_basename = 'offlineimapdoc' htmlhelp_basename = 'dev-doc'
# -- Options for LaTeX output -------------------------------------------------- # -- Options for LaTeX output --------------------------------------------------

View File

@ -3,13 +3,13 @@
.. currentmodule:: offlineimap .. currentmodule:: offlineimap
Welcome to :mod:`offlineimaps`'s documentation 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 <https://github.com/spaetz/offlineimap/wiki>`_. 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 homepage <http://offlineimap.org>`_.
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`. 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 <Sebastian@SSpaeth.de> .. moduleauthor:: John Goerzen, and many others. See AUTHORS and the git history for a full list.
:License: This module is covered under the GNU GPL v2 (or later). :License: This module is covered under the GNU GPL v2 (or later).
@ -24,59 +24,45 @@ More information on specific topics can be found on the following pages:
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 1
offlineimap repository
ui
offlineimap
:mod:`offlineimap` -- The OfflineImap module :mod:`offlineimap` -- The OfflineImap module
================================================= =============================================
.. automodule:: offlineimap .. module:: offlineimap
.. autoclass:: offlineimap.OfflineImap(cmdline_opts = None) .. autoclass:: offlineimap.OfflineImap(cmdline_opts = None)
.. automethod:: parse_commandline
.. automethod:: write_pidfile
.. automethod:: delete_pidfile
.. automethod:: lock .. automethod:: lock
.. automethod:: unlock .. automethod:: run
.. autoattribute:: ui .. .. autoattribute:: ui
:todo: Document :todo: Document
:mod:`offlineimap.folder` -- Basic representation of a local or remote Mail folder :class:`offlineimap.account`
--------------------------------------------------------------------------------------------------------- ============================
.. autoclass:: offlineimap.folder.Base.BaseFolder An :class:`accounts.Account` connects two email repositories that are to be synced. It comes in two flavors, normal and syncable.
.. autoclass:: offlineimap.accounts.Account
.. autoclass:: offlineimap.accounts.SyncableAccount
:members: :members:
:inherited-members: :inherited-members:
.. .. note:: :meth:`foo` .. autodata:: ui
.. .. attribute:: Database.MODE
Defines constants that are used as the mode in which to open a database. Contains the current :mod:`offlineimap.ui`, and can be used for logging etc.
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 :exc:`OfflineImapException` -- A Notmuch execution error
------------------------------------------------ --------------------------------------------------------
.. autoexception:: offlineimap.OfflineImapException .. autoexception:: offlineimap.OfflineImapException
:members: :members:
This execption inherits directly from :exc:`Exception` and is raised on errors during the notmuch execution. This execption inherits directly from :exc:`Exception` and is raised on errors during the offlineimap execution.
Indices and tables
==================
* :ref:`genindex`
* :ref:`search`

View File

@ -1,5 +1,5 @@
The offlineimap 'binary' The offlineimap 'binary' command line options
======================== =============================================
Offlineimap is invoked with the following pattern: `offlineimap [args...]`. Offlineimap is invoked with the following pattern: `offlineimap [args...]`.
@ -72,3 +72,12 @@ Options:
Possible interface choices are: Curses.Blinkenlights, Possible interface choices are: Curses.Blinkenlights,
TTY.TTYUI, Noninteractive.Basic, Noninteractive.Quiet, TTY.TTYUI, Noninteractive.Basic, Noninteractive.Quiet,
Machine.MachineUI Machine.MachineUI
Indices and tables
==================
* :ref:`genindex`
* :ref:`search`

View File

@ -0,0 +1,68 @@
.. currentmodule:: offlineimap.repository
:mod:`offlineimap.repository` -- Email repositories
------------------------------------------------------------
A derivative of class
:class:`Base.BaseRepository` represents an email
repository depending on the type of storage, possible options are:
* :class:`IMAPRepository`,
* :class:`MappedIMAPRepository`
* :class:`GmailRepository`,
* :class:`MaildirRepository`, or
* :class:`LocalStatusRepository`.
Which class you need depends on your account
configuration. The helper class :class:`offlineimap.repository.Repository` is
an *autoloader*, that returns the correct class depending
on your configuration. So when you want to instanciate a new
:mod:`offlineimap.repository`, you will mostly do it through this class.
.. autoclass:: offlineimap.repository.Repository
:members:
:inherited-members:
:mod:`offlineimap.repository` -- Basic representation of a mail repository
--------------------------------------------------------------------------
.. autoclass:: offlineimap.repository.Base.BaseRepository
:members:
:inherited-members:
:undoc-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
.. autoclass:: offlineimap.repository.IMAPRepository
.. autoclass:: offlineimap.repository.MappedIMAPRepository
.. autoclass:: offlineimap.repository.GmailRepository
.. autoclass:: offlineimap.repository.MaildirRepository
.. autoclass:: offlineimap.repository.LocalStatusRepository
:mod:`offlineimap.folder` -- Basic representation of a local or remote Mail folder
---------------------------------------------------------------------------------------------------------
.. autoclass:: offlineimap.folder.Base.BaseFolder
:members:
:inherited-members:
:undoc-members:
.. .. 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

27
docs/dev-doc-src/ui.rst Normal file
View File

@ -0,0 +1,27 @@
:mod:`offlineimap.ui` -- A pluggable logging system
--------------------------------------------------------
.. currentmodule:: offlineimap.ui
OfflineImap has various ui systems, that can be selected. They offer various functionalities. They must implement all functions that the :class:`offlineimap.ui.UIBase` offers. Early on, the ui must be set using :meth:`getglobalui`
.. automethod:: offlineimap.ui.setglobalui
.. automethod:: offlineimap.ui.getglobalui
Base UI plugin
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. autoclass:: offlineimap.ui.UIBase.UIBase
: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

View File

@ -105,11 +105,24 @@ def AccountHashGenerator(customconfig):
class Account(CustomConfig.ConfigHelperMixin): class Account(CustomConfig.ConfigHelperMixin):
"""Represents an account (ie. 2 repositories) to sync
Most of the time you will actually want to use the derived
:class:`accounts.SyncableAccount` which contains all functions used
for syncing an account."""
def __init__(self, config, name): def __init__(self, config, name):
"""
:param config: Representing the offlineimap configuration file.
:type config: :class:`offlineimap.CustomConfig.CustomConfigParser`
:param name: A string denoting the name of the Account
as configured"""
self.config = config self.config = config
self.name = name self.name = name
self.metadatadir = config.getmetadatadir() self.metadatadir = config.getmetadatadir()
self.localeval = config.getlocaleval() self.localeval = config.getlocaleval()
#Contains the current :mod:`offlineimap.ui`, and can be used for logging etc.
self.ui = getglobalui() self.ui = getglobalui()
self.refreshperiod = self.getconffloat('autorefresh', 0.0) self.refreshperiod = self.getconffloat('autorefresh', 0.0)
self.quicknum = 0 self.quicknum = 0
@ -171,9 +184,11 @@ class Account(CustomConfig.ConfigHelperMixin):
class SyncableAccount(Account): class SyncableAccount(Account):
"""A syncable IMAP account. """A syncable email account connecting 2 repositories
Derives from class:`Account`.""" Derives from :class:`accounts.Account` but contains the additional
functions :meth:`syncrunner`, :meth:`sync`, :meth:`syncfolders`,
used for syncing."""
def syncrunner(self, siglistener): def syncrunner(self, siglistener):
self.ui.registerthread(self.name) self.ui.registerthread(self.name)

View File

@ -41,9 +41,10 @@ lockfd = None
class OfflineImap: class OfflineImap:
"""The main class that encapsulates the high level use of OfflineImap. """The main class that encapsulates the high level use of OfflineImap.
To invoke OfflineImap you would call it with: To invoke OfflineImap you would call it with::
oi = OfflineImap()
oi.run() oi = OfflineImap()
oi.run()
""" """
def lock(self, config, ui): def lock(self, config, ui):
global lockfd, hasfcntl global lockfd, hasfcntl

View File

@ -31,9 +31,11 @@ debugtypes = {'imap': 'IMAP protocol debugging',
globalui = None globalui = None
def setglobalui(newui): def setglobalui(newui):
"""Set the global ui object to be used for logging"""
global globalui global globalui
globalui = newui globalui = newui
def getglobalui(): def getglobalui():
"""Return the current ui object"""
global globalui global globalui
return globalui return globalui