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

Improve documentation

Browse Source 
Improve wording, and integrate the MANUAL and INSTALL and FAQ documents
into our complete user manual that is hosted online.

Signed-off-by: Sebastian Spaeth <Sebastian@SSpaeth.de>
This commit is contained in:
Sebastian Spaeth 2012-01-17 01:34:56 +01:00
parent f2a94af522
commit 340c2f9a89
8 changed files with 192 additions and 144 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

170
docs/INSTALL.rst
View File

@ -1,81 +1,90 @@
.. -*- coding: utf-8 -*- .. -*- coding: utf-8 -*-
.. _OfflineIMAP: https://github.com/spaetz/offlineimap
.. _OfflineIMAP: https://github.com/nicolas33/offlineimap .. _OLI_git_repo: git://github.com/spaetz/offlineimap.git
.. contents::
.. sectnum::
=============
Prerequisites
=============
In order to use `OfflineIMAP`_, you need to have these conditions satisfied:
1. Your mail server must support IMAP. Most Internet Service Providers and
corporate networks do, and most operating systems have an IMAP implementation
readily available. A special Gmail mailbox type is available to interface with
Gmail's IMAP front-end.
2. You must have Python version 2.6 or above installed. If you are running on
Debian GNU/Linux, this requirement will automatically be taken care of for you.
If you do not have Python already, check with your system administrator or
operating system vendor; or, download it from the Python website. If you intend
to use the SSL interface, your Python must have been built with SSL support.
3. Have a mail reader that supports the Maildir mailbox format. Most modern
mail readers have this support built-in, so you can choose from a wide variety
of mail servers. This format is also known as the "qmail" format, so any mail
reader compatible with it will work with `OfflineIMAP`_. If you do not have a
mail reader that supports Maildir, you can often install a local IMAP server and
point both `OfflineIMAP`_ and your mail reader at it.
============ ============
Installation Installation
============ ============
You have three options: .. contents::
.. .. sectnum::
1. a system-wide installation with Debian -------------
2. a system-wide installation with other systems Prerequisites
3. a single-user installation. You can checkout the latest version of -------------
`OfflineIMAP`_ from official `OfflineIMAP`_ repository.
In order to use `OfflineIMAP`_, you need to have these conditions satisfied:
1. Your mail server must support IMAP. Mail access via POP is not
supported. A special Gmail mailbox type is available to interface
with Gmail's IMAP front-end, although Gmail has a very peculiar and
non-standard implementation of its IMAP interface.
2. You must have Python version 2.6 or above installed. If you are
running on Debian GNU/Linux, this requirement will automatically be
taken care of for you. If you intend to use the SSL interface,
your Python must have been built with SSL support.
3. If you use OfflineImap as an IMAP<->Maildir synchronizer, you will
obviously need to have a mail reader that supports the Maildir
mailbox format. Most modern mail readers have this support built-in,
so you can choose from a wide variety of mail servers. This format
is also known as the "qmail" format, so any mail reader compatible
with it will work with `OfflineIMAP`_.
System-Wide Installation, Debian ------------
================================ Installation
------------
If you are tracking Debian unstable, you may install `OfflineIMAP`_ by simply Installing OfflineImap should usually be quite easy, as you can simply unpack and run OfflineImap in place if you wish to do so. There are a number of options though:
running the following command as root::
apt-get install offlineimap #. system-wide :ref:`installation via your distribution package manager <inst_pkg_man>`
#. system-wide or single user :ref:`installation from the source package <inst_src_tar>`
#. system-wide or single user :ref:`installation from a git checkout <inst_git>`
If you are not tracking Debian unstable, download the Debian `.deb` package from Having installed OfflineImap, you will need to configure it, to be actually useful. Please check the :ref:`Configuration` section in the :doc:`MANUAL` for more information on the configuration step.
the `OfflineIMAP`_ website and then run ``dpkg -i`` to install the downloaded
package. Then, skip to below. You will type offlineimap to invoke the
program.
System-Wide Installation, Other .. _inst_pkg_man:
===============================
Check your distribution packaging tool, OfflineIMAP may already be packaged for System-Wide Installation via distribution
you. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The easiest way to install OfflineIMAP is via your distribution's package manager. OfflineImap is available under the name `offlineimap` in most Linux and BSD distributions.
System-Wide Installation, From source
=====================================
Get your own copy of the official git repository at `OfflineIMAP`_:: .. _inst_src_tar:
git clone git://github.com/nicolas33/offlineimap.git Installation from source package
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Download the latest source archive from our `download page <https://github.com/spaetz/offlineimap/downloads>`_. Simply click the "Download as .zip" or "Download as .tar.gz" buttons to get the latest "stable" code from the master branch. If you prefer command line, you will want to use:
wget https://github.com/spaetz/offlineimap/tarball/master
This will download all the sources with history. By default, git set up the Unpack and continue with the :ref:`system-wide installation <system_wide_inst>` or the :ref:`single-user installation <single_user_inst>` section.
local master branch up which is most likely what you want. If not, you can
checkout a particular release::
.. _inst_git:
Installation from git checkout
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Get your own copy of the `official git repository <OLI_git_repo>`_ at `OfflineIMAP`_::
git clone git://github.com/spaetz/offlineimap.git
This will download the source with history. By default, git sets up the
`master` branch up, which is most likely what you want. If not, you can
checkout a particular release like this::
cd offlineimap cd offlineimap
git checkout -b local_version v6.3.3 git checkout v6.5.2.1
The latter creates a local branch called "local_version" of the v6.3.3 release. You have now a source tree available and proceed with either the :ref:`system-wide installation <system_wide_inst>` or the :ref:`single-user installation <single_user_inst>`.
.. _system_wide_inst:
System-wide installation
++++++++++++++++++++++++
Then run these commands, to build the python package:: Then run these commands, to build the python package::
@ -86,47 +95,38 @@ Finally, install the program (as root)::
python setup.py install python setup.py install
Next, proceed to below. You will type offlineimap to invoke the program. Next, proceed to below. You tofflineimap to invoke the program.
Single-Account Installation
=========================== .. _single_user_inst:
Single-user installation
++++++++++++++++++++++++
Download the git repository as described above. Instead of installing the Download the git repository as described above. Instead of installing the
program as root, you type `./offlineimap.py`; there is no installation step program as root, you type `./offlineimap.py`; there is no installation step
necessary. necessary.
============= ---------
Configuration
=============
`OfflineIMAP`_ is regulated by a configuration file that is normally stored in
`~/.offlineimaprc`. `OfflineIMAP`_ ships with a file named `offlineimap.conf`
that you should copy to that location and then edit. This file is vital to
proper operation of the system; it sets everything you need to run
`OfflineIMAP`_. Full documentation for the configuration file is included
within the sample file.
`OfflineIMAP`_ also ships a file named `offlineimap.conf.minimal` that you can
also try. It's useful if you want to get started with the most basic feature
set, and you can read about other features later with `offlineimap.conf`.
===============
Uninstall Uninstall
=============== ---------
If you installed a system-wide installation via "python setup.py If you installed a system-wide installation via "python setup.py
install", there are a few files to purge to uninstall it again. I assume install", there are a few files to purge to cleanly uninstall
that /usr/local is the standard prefix that your system and you use `OfflineImap`_ again. Assuming that `/usr/local` is the standard prefix of
python 2.7. Adapt to your system. In that case you need to: your system and that you use python 2.7, you need to:
#) Delete the OfflineImap installation itself::
1) Delete:
/usr/local/lib/python2.7/dist-packages/offlineimap-6.4.4.egg-info /usr/local/lib/python2.7/dist-packages/offlineimap-6.4.4.egg-info
/usr/local/lib/python2.7/dist-packages/offlineimap /usr/local/lib/python2.7/dist-packages/offlineimap
2) Delete the cache at (default location) ~/.offlineimap In case, you did the single-user installation, simply delete your
Delete your manually created (default loc) ~/.offlineimaprc offlineimap directory.
#) Delete all files that OfflineImap creates during its operation.
- The cache at (default location) ~/.offlineimap
- Your manually created (default loc) ~/.offlineimaprc
(It is possible that you created those in different spots) (It is possible that you created those in different spots)
That's it. Have fun without OfflineImap. That's it. Have fun without OfflineImap.

17
docs/MANUAL.rst
View File

@ -43,6 +43,23 @@ Most configuration is done via the configuration file. However, any setting can
OfflineImap is well suited to be frequently invoked by cron jobs, or can run in daemon mode to periodically check your email (however, it will exit in some error situations). OfflineImap is well suited to be frequently invoked by cron jobs, or can run in daemon mode to periodically check your email (however, it will exit in some error situations).
.. _configuration:
Configuration
=============
`OfflineIMAP`_ is regulated by a configuration file that is normally stored in
`~/.offlineimaprc`. `OfflineIMAP`_ ships with a file named `offlineimap.conf`
that you should copy to that location and then edit. This file is vital to
proper operation of the system; it sets everything you need to run
`OfflineIMAP`_. Full documentation for the configuration file is included
within the sample file.
`OfflineIMAP`_ also ships a file named `offlineimap.conf.minimal` that you can
also try. It's useful if you want to get started with the most basic feature
set, and you can read about other features later with `offlineimap.conf`.
Check out the `Use Cases`_ section for some example configurations. Check out the `Use Cases`_ section for some example configurations.

55
docs/dev-doc-src/API.rst Normal file
View File

@ -0,0 +1,55 @@
.. OfflineImap API documentation
.. currentmodule:: offlineimap
Welcome to :mod:`offlineimaps`'s documentation
==============================================
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. Email repositories are represented by a :class:`offlineimap.repository.Base.BaseRepository` or derivatives (see :mod:`offlineimap.repository` for details). A folder within a repository is represented by a :class:`offlineimap.folder.Base.BaseFolder` or any derivative from :mod:`offlineimap.folder`.
This page contains the main API overview of OfflineImap |release|.
OfflineImap can be imported as::
from offlineimap import OfflineImap
:mod:`offlineimap` -- The OfflineImap module
=============================================
.. module:: offlineimap
.. autoclass:: offlineimap.OfflineImap(cmdline_opts = None)
.. automethod:: run
.. automethod:: parse_cmd_options
.. .. autoattribute:: ui
:todo: Document
:class:`offlineimap.account`
============================
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:
.. autodata:: ui
Contains the current :mod:`offlineimap.ui`, and can be used for logging etc.
:exc:`OfflineImapError` -- A Notmuch execution error
--------------------------------------------------------
.. autoexception:: offlineimap.error.OfflineImapError
:members:
This execption inherits directly from :exc:`Exception` and is raised
on errors during the offlineimap execution. It has an attribute
`severity` that denotes the severity level of the error.

1
docs/dev-doc-src/FAQ.rst Symbolic link
View File

@ -0,0 +1 @@
../FAQ.rst

1
docs/dev-doc-src/INSTALL.rst Symbolic link
View File

@ -0,0 +1 @@
../INSTALL.rst

1
docs/dev-doc-src/MANUAL.rst Symbolic link
View File

@ -0,0 +1 @@
../MANUAL.rst

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

@ -94,7 +94,7 @@ pygments_style = 'sphinx'
# The theme to use for HTML and HTML Help pages. Major themes that come with # The theme to use for HTML and HTML Help pages. Major themes that come with
# Sphinx are currently 'default' and 'sphinxdoc'. # Sphinx are currently 'default' and 'sphinxdoc'.
html_theme = 'default' html_theme = 'default'
#html_style = ''
# Theme options are theme-specific and customize the look and feel of a theme # Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the # further. For a list of options available for each theme, see the
# documentation. # documentation.

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

@ -1,69 +1,42 @@
.. OfflineImap documentation master file .. OfflineImap documentation master file
.. _OfflineImap: http://offlineimap.org
.. 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 homepage <http://offlineimap.org>`_. The following provides the developer documentation for those who are interested in modifying the source code or otherwise peek into the OfflineImap internals. End users might want to check the MANUAL, our INSTALLation instructions, and the FAQ. `OfflineImap`_ synchronizes email between an IMAP server and a MailDir or between two IMAP servers. It offers very powerful and flexible configuration options, that allow things such as the filtering of folders, transposing of names via static configuration or python scripting. It plays well with mutt and other MailDir consuming email clients.
The documentation contains the end user documentation in a first part. It also contains use cases and example configurations. It is followed by the internal :doc:`API documentation <API>` for those interested in modifying the source code or otherwise peek into the OfflineImap internals in a second part.
If you just want to get started with minimal fuzz, have a look at our `online quick start guide <http://offlineimap.org/#ref-quick-start>`_. Do note though, that our configuration options are many and powerful. Perusing our precious documentation does often pay off!
More information on specific topics can be found on the following pages:
**User documentation**
* :doc:`installation/uninstall <INSTALL>`
* :doc:`user manual/Configuration <MANUAL>`
* :doc:`command line options <offlineimap>`
* :doc:`Frequently Asked Questions <FAQ>`
**Developer documentation**
* :doc:`API documentation <API>` for internal details on the
:mod:`offlineimap` module
.. toctree::
:hidden:
INSTALL
MANUAL
offlineimap
FAQ
API
repository
ui
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. Email repositories are represented by a :class:`offlineimap.repository.Base.BaseRepository` or derivatives (see :mod:`offlineimap.repository` for details). A folder within a repository is represented by a :class:`offlineimap.folder.Base.BaseFolder` or any derivative from :mod:`offlineimap.folder`.
.. moduleauthor:: John Goerzen, and many others. See AUTHORS and the git history for a full list. .. 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).
This page contains the main API overview of OfflineImap |release|.
OfflineImap can be imported as::
from offlineimap import OfflineImap
More information on specific topics can be found on the following pages:
.. toctree::
:maxdepth: 1
repository
ui
offlineimap
:mod:`offlineimap` -- The OfflineImap module
=============================================
.. module:: offlineimap
.. autoclass:: offlineimap.OfflineImap(cmdline_opts = None)
.. automethod:: lock
.. automethod:: run
.. .. autoattribute:: ui
:todo: Document
:class:`offlineimap.account`
============================
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:
.. autodata:: ui
Contains the current :mod:`offlineimap.ui`, and can be used for logging etc.
:exc:`OfflineImapError` -- A Notmuch execution error
--------------------------------------------------------
.. autoexception:: offlineimap.error.OfflineImapError
:members:
This execption inherits directly from :exc:`Exception` and is raised
on errors during the offlineimap execution. It has an attribute
`severity` that denotes the severity level of the error.