tobias/docker-offlineimap
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve the developer API documentation

Browse Source 
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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/dev-doc-src/conf.py
View File

@ -122,7 +122,7 @@ html_theme = 'default'
# 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']
#html_static_path = ['html']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
@ -160,7 +160,7 @@ html_use_modindex = False
#html_file_suffix = ''
# Output file base name for HTML help builder.
htmlhelp_basename = 'offlineimapdoc'
htmlhelp_basename = 'dev-doc'
# -- Options for LaTeX output --------------------------------------------------

56
docs/dev-doc-src/index.rst
View File

@ -3,13 +3,13 @@
.. 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 <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`.
.. 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).
@ -24,59 +24,45 @@ More information on specific topics can be found on the following pages:
.. toctree::
:maxdepth: 1
repository
ui
offlineimap
:mod:`offlineimap` -- The OfflineImap module
=================================================
=============================================
.. automodule:: offlineimap
.. module:: offlineimap
.. autoclass:: offlineimap.OfflineImap(cmdline_opts = None)
.. automethod:: parse_commandline
.. automethod:: write_pidfile
.. automethod:: delete_pidfile
.. automethod:: lock
.. automethod:: unlock
.. automethod:: run
.. autoattribute:: ui
.. .. autoattribute:: ui
: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:
:inherited-members:
.. .. note:: :meth:`foo`
.. .. attribute:: Database.MODE
.. autodata:: ui
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
Contains the current :mod:`offlineimap.ui`, and can be used for logging etc.
: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`
This execption inherits directly from :exc:`Exception` and is raised on errors during the offlineimap execution.

13
docs/dev-doc-src/offlineimap.rst
View File

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

68
docs/dev-doc-src/repository.rst Normal file
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

19
offlineimap/accounts.py
View File

@ -105,11 +105,24 @@ def AccountHashGenerator(customconfig):
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):
"""
: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.name = name
self.metadatadir = config.getmetadatadir()
self.localeval = config.getlocaleval()
#Contains the current :mod:`offlineimap.ui`, and can be used for logging etc.
self.ui = getglobalui()
self.refreshperiod = self.getconffloat('autorefresh', 0.0)
self.quicknum = 0
@ -171,9 +184,11 @@ class Account(CustomConfig.ConfigHelperMixin):
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):
self.ui.registerthread(self.name)

7
offlineimap/init.py
View File

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

2
offlineimap/ui/UIBase.py
View File

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