* Introduce the new documentation and add 0.7.9~exp2 to changelog.

The new documentation is built using sphinx (>= 0.5) [other versions may work too,
but let's be safe].

2 files changed, 334 insertions, 0 deletions

diff --git a/doc/source/apt_pkg/cache.rst b/doc/source/apt_pkg/cache.rst
new file mode 100644
index 00000000..abb0fab2
--- /dev/null
+++ b/doc/source/apt_pkg/cache.rst
@@ -0,0 +1,95 @@
+Low-Level Cache Handling
+===========================
+
+.. class:: Acquire
+
+    .. method:: Run()
+
+        Fetch all the items which have been added by
+        :func:`apt_pkg.GetPkgAcqFile`.
+
+    .. method:: Shutdown
+
+        Shut the fetcher down.
+
+.. class:: pkgCache
+
+    The :class:`pkgCache` class prov
+
+    .. method:: Close()
+
+        Close the package cache.
+
+    .. method:: Open([progress])
+
+        Open the package cache again. The parameter ``progress`` may be set to
+        an :class:`apt.progress.OpProgress()` object or `None`.
+
+    .. method:: Update(progress, list)
+
+        Update the package cache.
+
+        The parameter ``progress`` points to an :class:`apt.progress.FetchProgress()`
+        object.
+
+        The parameter ``list`` refers to an object as returned by
+        :func:`apt_pkg.GetPkgSourceList`.
+
+    .. method:: __getitem__(item)
+
+        Return an :class:`pkgCachePackage` object for the package with the given
+        name.
+
+.. class:: pkgCachePackage
+
+    The pkgCache::Package objects are an interface to package specific
+    features.
+
+
+    Attributes:
+
+    .. attribute:: Name
+
+        This is the name of the package.
+
+    .. attribute:: Section
+
+        The section of the package, as specified in the record. The list of
+        possible sections is defined in the Policy.
+
+    .. attribute:: ID
+
+        The ID of the package. This can be used to store information about
+        the package. The ID is an int value.
+
+
+Working with dependencies
+-------------------------
+.. class:: pkgDepCache
+
+    The pkgDepCache object contains various methods to manipulate the cache,
+    to install packages, to remove them, and much more.
+
+    .. method:: Commit(fprogress, iprogress)
+
+        Apply all the changes made.
+
+        The parameter ``fprogress`` has to be set to an instance of
+        apt.progress.FetchProgress or one of its subclasses.
+
+        The parameter ``iprogress`` has to be set to an instance of
+        apt.progress.InstallProgress or one of its subclasses.
+
+    .. method:: FixBroken()
+
+        Try to fix all broken packages in the cache.
+
+    .. method:: GetCandidateVer(pkg)
+
+        Return the candidate version of the package, ie. the version that
+        would be installed normally.
+
+        The parameter ``pkg`` refers to an :class:`pkgCachePackage` object,
+        available using the :class:`pkgCache`.
+
+        This method returns a :class:`pkgCacheVersion` object.
diff --git a/doc/source/apt_pkg/index.rst b/doc/source/apt_pkg/index.rst
new file mode 100644
index 00000000..5f23df31
--- /dev/null
+++ b/doc/source/apt_pkg/index.rst
@@ -0,0 +1,239 @@
+:mod:`apt_pkg` --- The low-level bindings for apt-pkg
+=====================================================
+.. module:: apt_pkg
+
+The apt_pkg extensions provides a more low-level way to work with apt. It can
+do everything apt can, and is written in C++. It has been in python-apt since
+the beginning.
+
+
+.. toctree::
+    :maxdepth: 2
+    :glob:
+
+    *
+
+
+Module Initialization
+---------------------
+
+
+.. function:: initConfig
+
+    Initialize the configuration of apt. This is needed for most operations.
+
+.. function:: initSystem
+
+    Initialize the system.
+
+.. function:: init
+
+    Deprecated function. Use initConfig() and initSystem() instead.
+
+Object initialization
+----------------------
+.. function:: GetCache([progress])
+
+    Return a :class:`pkgCache` object. The optional parameter ``progress``
+    specifies an instance of :class:`apt.progress.OpProgress()` which will
+    display the open progress.
+
+.. function:: GetCdrom()
+
+    Return a Cdrom object with the following methods:
+
+    .. method:: Cdrom.Ident(progress)
+
+        Identify the cdrom. The parameter ``progress`` refers to an
+        :class:`apt.progress.CdromProgress()` object.
+
+    .. method:: Cdrom.Add(progress)
+
+        Add the cdrom to the sources.list file. The parameter ``progress``
+        refers to an :class:`apt.progress.CdromProgress()` object.
+
+
+
+.. function:: GetDepCache(cache)
+
+    Return a :class:`pkgDepCache` object. The parameter ``cache`` specifies an
+    instance of :class:`pkgCache` (see :func:`GetCache()`).
+
+
+.. function:: GetPkgSourceList()
+
+    Return a :class:`pkgSourceList` object.
+
+
+The Acquire interface
+----------------------
+.. function:: GetAcquire([progress])
+
+    Return an :class:`Acquire` object. This is a class which allows you
+    to fetch files, or archive contents. The parameter ``progress`` refers to
+    an :class:`apt.progress.FetchProgress()` object.
+
+    Acquire items have multiple methods:
+
+    .. method:: Acquire.Run()
+
+        Fetch all the items which have been added by :func:`GetPkgAcqFile`.
+
+    .. method:: Acquire.Shutdown()
+
+        Shut the fetcher down.
+
+.. function:: GetPkgAcqFile(aquire, uri[, md5, size, descr, shortDescr, destDir, destFile])
+
+    The parameter ``acquire`` refers to an :class:`Acquire()` object as returned
+    by :func:`GetAcquire`. The file will be added to the Acquire queue
+    automatically.
+
+    The parameter ``uri`` refers to the location of the file, any protocol
+    of apt is supported.
+
+    The parameter ``md5`` refers to the md5sum of the file. This can be used
+    for checking the file.
+
+    The parameter ``size`` can be used to specify the size of the package,
+    which can then be used to calculate the progress and validate the download.
+
+    The parameter ``descr`` is a descripition of the download. It may be
+    used to describe the item in the progress class. ``shortDescr`` is the
+    short form of it.
+
+    You can use ``destDir`` to manipulate the directory where the file will
+    be saved in. Together with ``destFile`` you can specify the complete target
+    path.
+
+
+
+Hash functions
+--------------
+The apt_pkg module also provides several hash functions. If you develop
+applications with python-apt it is often easier to use these functions instead
+of the ones provides in Python's :mod:`hashlib` module.
+
+.. function:: md5sum(object)
+
+    Return the md5sum of the object. ``object`` may either be a string, in
+    which case the md5sum of the string is returned, or a :class:`file()`
+    object, in which case the md5sum of its contents is returned.
+
+.. function:: sha1sum(object)
+
+    Return the sha1sum of the object. ``object`` may either be a string, in
+    which case the sha1sum of the string is returned, or a :class:`file()`
+    object, in which case the sha1sum of its contents is returned.
+
+.. function:: sha256sum(object)
+
+    Return the sha256sum of the object. ``object`` may either be a string, in
+    which case the sha256sum of the string is returned, or a :class:`file()`
+    object, in which case the sha256sum of its contents is returned.
+
+Other functions
+----------------
+
+.. note::
+
+    This documentation is created automatically and should be rewritten.
+
+.. autofunction:: Base64Encode
+.. autofunction:: CheckDep
+.. autofunction:: CheckDomainList
+.. autofunction:: DeQuoteString
+.. autofunction:: GetLock
+.. autofunction:: GetPackageManager
+.. autofunction:: GetPkgActionGroup
+.. autofunction:: GetPkgProblemResolver
+.. autofunction:: GetPkgRecords
+.. autofunction:: GetPkgSrcRecords
+.. autofunction:: newConfiguration
+.. autofunction:: ParseCommandLine
+.. autofunction:: ParseDepends
+.. autofunction:: ParseSection
+.. autofunction:: ParseSrcDepends
+.. autofunction:: ParseTagFile
+.. autofunction:: PkgSystemLock
+.. autofunction:: PkgSystemUnLock
+.. autofunction:: QuoteString
+.. autofunction:: ReadConfigFile
+.. autofunction:: ReadConfigFileISC
+.. autofunction:: RewriteSection
+.. autofunction:: SizeToStr
+.. autofunction:: StringToBool
+.. autofunction:: StrToTime
+.. autofunction:: TimeRFC1123
+.. autofunction:: TimeToStr
+.. autofunction:: UpstreamVersion
+.. autofunction:: URItoFileName
+.. autofunction:: VersionCompare
+
+
+Data
+-----
+
+.. data:: Config
+
+    An :class:`Configuration()` object with the default configuration. Actually,
+    this is a bit different object, but it is compatible.
+
+.. data:: RewritePackageOrder
+
+.. data:: RewriteSourceOrder
+
+
+Package States
+^^^^^^^^^^^^^^^
+.. data:: CurStateConfigFiles
+.. data:: CurStateHalfConfigured
+.. data:: CurStateHalfInstalled
+.. data:: CurStateInstalled
+.. data:: CurStateNotInstalled
+.. data:: CurStateUnPacked
+
+
+
+
+Dependency types
+^^^^^^^^^^^^^^^^
+.. data:: DepConflicts
+.. data:: DepDepends
+.. data:: DepObsoletes
+.. data:: DepPreDepends
+.. data:: DepRecommends
+.. data:: DepReplaces
+.. data:: DepSuggests
+
+Installed states
+^^^^^^^^^^^^^^^^^
+.. data:: InstStateHold
+.. data:: InstStateHoldReInstReq
+.. data:: InstStateOk
+.. data:: InstStateReInstReq
+
+
+Priorities
+^^^^^^^^^^
+.. data:: PriExtra
+.. data:: PriImportant
+.. data:: PriOptional
+.. data:: PriRequired
+.. data:: PriStandard
+
+Dselect states
+^^^^^^^^^^^^^^
+.. data:: SelStateDeInstall
+.. data:: SelStateHold
+.. data:: SelStateInstall
+.. data:: SelStatePurge
+.. data:: SelStateUnknown
+
+
+Build information
+^^^^^^^^^^^^^^^^^
+.. data:: Date
+.. data:: LibVersion
+.. data:: Time
+.. data:: Version