From 6add201436ff468d24ac2e75dac3b8aef43bdf1d Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Mon, 2 May 2011 17:11:40 +0200 Subject: [PATCH] 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 Signed-off-by: Nicolas Sebrecht --- docs/dev-doc-src/conf.py | 4 +- docs/dev-doc-src/index.rst | 58 +++++++++++---------------- docs/dev-doc-src/offlineimap.rst | 13 +++++- docs/dev-doc-src/repository.rst | 68 ++++++++++++++++++++++++++++++++ docs/dev-doc-src/ui.rst | 27 +++++++++++++ offlineimap/accounts.py | 19 ++++++++- offlineimap/init.py | 7 ++-- offlineimap/ui/UIBase.py | 2 + 8 files changed, 153 insertions(+), 45 deletions(-) create mode 100644 docs/dev-doc-src/repository.rst create mode 100644 docs/dev-doc-src/ui.rst diff --git a/docs/dev-doc-src/conf.py b/docs/dev-doc-src/conf.py index 9269a51..f583a9c 100644 --- a/docs/dev-doc-src/conf.py +++ b/docs/dev-doc-src/conf.py @@ -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 -------------------------------------------------- diff --git a/docs/dev-doc-src/index.rst b/docs/dev-doc-src/index.rst index dff8620..f4d7067 100644 --- a/docs/dev-doc-src/index.rst +++ b/docs/dev-doc-src/index.rst @@ -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 `_. +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 `_. 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 +.. 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 - offlineimap + 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. diff --git a/docs/dev-doc-src/offlineimap.rst b/docs/dev-doc-src/offlineimap.rst index f206c11..bc98c16 100644 --- a/docs/dev-doc-src/offlineimap.rst +++ b/docs/dev-doc-src/offlineimap.rst @@ -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` + diff --git a/docs/dev-doc-src/repository.rst b/docs/dev-doc-src/repository.rst new file mode 100644 index 0000000..04025cd --- /dev/null +++ b/docs/dev-doc-src/repository.rst @@ -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 diff --git a/docs/dev-doc-src/ui.rst b/docs/dev-doc-src/ui.rst new file mode 100644 index 0000000..03da19b --- /dev/null +++ b/docs/dev-doc-src/ui.rst @@ -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 diff --git a/offlineimap/accounts.py b/offlineimap/accounts.py index 6b706de..c366810 100644 --- a/offlineimap/accounts.py +++ b/offlineimap/accounts.py @@ -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) diff --git a/offlineimap/init.py b/offlineimap/init.py index 84983a4..54e7a27 100644 --- a/offlineimap/init.py +++ b/offlineimap/init.py @@ -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 diff --git a/offlineimap/ui/UIBase.py b/offlineimap/ui/UIBase.py index 02593e6..150818d 100644 --- a/offlineimap/ui/UIBase.py +++ b/offlineimap/ui/UIBase.py @@ -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