[PATCH] Improve the developer API documentation
Sebastian Spaeth
Sebastian at SSpaeth.de
Mon May 2 16:11:40 BST 2011
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 at SSpaeth.de>
---
Continue to build on what we already have. Plese see
http://sspaeth.de/uploads/tmp/html/index.html
for an example of how the current docs look when compiled.
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 <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 at 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
- 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
- :members:
- :inherited-members:
+An :class:`accounts.Account` connects two email repositories that are to be synced. It comes in two flavors, normal and syncable.
-.. .. note:: :meth:`foo`
-.. .. attribute:: Database.MODE
+.. autoclass:: offlineimap.accounts.Account
- Defines constants that are used as the mode in which to open a database.
+.. autoclass:: offlineimap.accounts.SyncableAccount
+ :members:
+ :inherited-members:
- MODE.READ_ONLY
- Open the database in read-only mode
+ .. autodata:: ui
- 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
--
1.7.4.1
More information about the OfflineIMAP-project
mailing list