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:
parent
e9a7afda6d
commit
6add201436
@ -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 --------------------------------------------------
|
||||||
|
@ -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`
|
|
||||||
|
|
||||||
|
@ -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`
|
||||||
|
|
||||||
|
68
docs/dev-doc-src/repository.rst
Normal file
68
docs/dev-doc-src/repository.rst
Normal 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
27
docs/dev-doc-src/ui.rst
Normal 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
|
@ -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)
|
||||||
|
@ -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
|
||||||
|
@ -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
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user