* doc/source/*: Improve the documentation

  - Document more attributes and functions of apt_pkg (they are all listed)

3 files changed, 173 insertions, 37 deletions

diff --git a/doc/source/apt/package.rst b/doc/source/apt/package.rst
index 6781717c..bb74915e 100644
--- a/doc/source/apt/package.rst
+++ b/doc/source/apt/package.rst
@@ -10,6 +10,11 @@ The Package class
 .. autoclass:: Package
     :members:
 
+    .. note::
+
+        Several methods have been deprecated in version 0.7.9 of python-apt,
+        please see the :class:`Version` class for the new alternatives.
+
 The Version class
 -----------------
 .. autoclass:: Version
@@ -93,14 +98,14 @@ Examples
 
     cache = apt.Cache()
     pkg = cache['python-apt'] # Access the Package object for python-apt
-    print 'python-apt is trusted:', pkg.candidateOrigin.trusted
+    print 'python-apt is trusted:', pkg.candidate.origins[0].trusted
 
     # Mark python-apt for install
     pkg.markInstall()
 
     print 'python-apt is marked for install:', pkg.markedInstall
 
-    print 'python-apt is', pkg.summary #Python interface to libapt-pkg
+    print 'python-apt is (summary):', pkg.candidate.summary
 
     # Now, really install it
     cache.commit()
diff --git a/doc/source/apt_pkg/index.rst b/doc/source/apt_pkg/index.rst
index 1c5866a9..e944eb15 100644
--- a/doc/source/apt_pkg/index.rst
+++ b/doc/source/apt_pkg/index.rst
@@ -34,7 +34,7 @@ Object initialization
 ----------------------
 .. function:: GetCache([progress])
 
-    Return a :class:`pkgCache` object. The optional parameter ``progress``
+    Return a :class:`pkgCache` object. The optional parameter *progress*
     specifies an instance of :class:`apt.progress.OpProgress()` which will
     display the open progress.
 
@@ -44,25 +44,54 @@ Object initialization
 
     .. method:: Cdrom.Ident(progress)
 
-        Identify the cdrom. The parameter ``progress`` refers to an
+        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``
+        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
+    Return a :class:`pkgDepCache` object. The parameter *cache* specifies an
     instance of :class:`pkgCache` (see :func:`GetCache()`).
 
 
 .. function:: GetPkgSourceList()
 
-    Return a :class:`pkgSourceList` object.
+    Return a :class:`PkgSourceList` object.
+
+.. function:: GetPackageManager(depcache)
+
+    Return a new :class:`PkgManager` object. The parameter *depcache* specifies
+    a :class:`pkgDepCache` object as returned by :func:`GetDepCache`.
+
+.. function:: GetPkgActionGroup(depcache)
+
+    Return a new :class:`ActionGroup` object. The parameter *depcache*
+    specifies a :class:`pkgDepCache` object as returned by :func:`GetDepCache`.
+
+.. function:: GetPkgProblemResolver(depcache)
+
+    Return a new :class:`ProblemResolver` object. The parameter *depcache*
+    specifies a :class:`pkgDepCache` object as returned by :func:`GetDepCache`.
+
+.. function:: GetPkgRecords(cache)
+
+    Return a new :class:`PkgRecords` object.
+
+    The parameter *cache* refers to an :class:`pkgCache` object, as returned
+    by :func:`GetCache`.
+
+.. function:: GetPkgSrcRecords()
+
+    Return a new :class:`PkgSrcRecords` object.
+
+.. function:: newConfiguration()
+
+    Return a new :class:`Configuration` object.
 
 
 The Acquire interface
@@ -70,7 +99,7 @@ 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
+    to fetch files, or archive contents. The parameter *progress* refers to
     an :class:`apt.progress.FetchProgress()` object.
 
     Acquire items have multiple methods:
@@ -99,26 +128,29 @@ The Acquire interface
 
 .. function:: GetPkgAcqFile(aquire, uri[, md5, size, descr, shortDescr, destDir, destFile])
 
-    The parameter ``acquire`` refers to an :class:`Acquire()` object as returned
+    Create a new :class:`PkgAcqFile()` object and register it with *acquire*,
+    so it will be fetched.
+
+    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
+    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
+    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,
+    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
+    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.
+    You can use *destDir* to manipulate the directory where the file will
+    be saved in. Instead of *destDir*, you can also specify the full path to
+    the file using the parameter *destFile*. You can not combine both.
 
 
 
@@ -130,19 +162,19 @@ 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
+    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
+    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
+    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.
 
@@ -151,19 +183,15 @@ Other functions
 
 .. note::
 
-    This documentation is created automatically and should be rewritten.
+    This documentation is (in parts) created automatically, and still needs to
+    be improved.
 
 .. 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
@@ -175,14 +203,105 @@ Other functions
 .. autofunction:: ReadConfigFile
 .. autofunction:: ReadConfigFileISC
 .. autofunction:: RewriteSection
-.. autofunction:: SizeToStr
-.. autofunction:: StringToBool
-.. autofunction:: StrToTime
-.. autofunction:: TimeRFC1123
-.. autofunction:: TimeToStr
-.. autofunction:: UpstreamVersion
-.. autofunction:: URItoFileName
-.. autofunction:: VersionCompare
+
+.. function:: SizeToStr(size)
+
+    Return a string presenting the human-readable version of the integer
+    *size*. When calculating the units (k,M,G,etc.) the size is divided by the
+    factor 1000.
+
+    Example::
+
+        >>> apt_pkg.SizeToStr(10000)
+        '10.0k'
+
+.. function:: StringToBool(input)
+
+    Parse the string *input* and return one of **-1**, **0**, **1**.
+
+    .. table:: Return values
+
+        ===== =============================================
+        Value      Meaning
+        ===== =============================================
+         -1   The string *input* is not recognized.
+          0   The string *input* evaluates to **False**.
+         +1   The string *input* evaluates to **True**.
+        ===== =============================================
+
+    Example::
+
+        >>> apt_pkg.StringToBool("yes")
+        1
+        >>> apt_pkg.StringToBool("no")
+        0
+        >>> apt_pkg.StringToBool("not-recognized")
+        -1
+
+.. function:: StrToTime(rfc_time)
+
+    Convert the :rfc:`1123` conforming string *rfc_time* to the unix time, and
+    return the integer. This is the opposite of :func:`TimeRFC1123`.
+
+    Example::
+
+        >> apt_pkg.StrToTime('Thu, 01 Jan 1970 00:00:00 GMT')
+        0
+
+.. function:: TimeRFC1123(seconds)
+
+    Format the unix time specified by the integer *seconds*, according to the
+    requirements of :rfc:`1123`.
+
+    Example::
+
+        >>> apt_pkg.TimeRFC1123(0)
+        'Thu, 01 Jan 1970 00:00:00 GMT'
+
+
+.. function:: TimeToStr(seconds)
+
+    Format a given duration in a human-readable manner. The parameter *seconds*
+    refers to a number of seconds, given as an integer. The return value is a
+    string with a unit like 's' for seconds.
+
+    Example::
+
+        >>> apt_pkg.TimeToStr(3601)
+        '1h0min1s'
+
+
+
+.. function:: UpstreamVersion(version)
+
+    Return the string *version*, eliminating everything following the last
+    '-'. Thus, this should be equivalent to ``version.rsplit('-', 1)[0]``.
+
+.. function:: URItoFileName(uri)
+
+    Take a string *uri* as parameter and return a filename which can be used to
+    store the file, based on the URI.
+
+    Example::
+
+        >>> apt_pkg.URItoFileName('http://debian.org/index.html')
+        'debian.org_index.html'
+
+
+.. function:: VersionCompare(a, b)
+
+    Compare two versions, *a* and *b*, and return an integer value which has
+    the same characteristic as the built-in :func:`cmp` function.
+
+    .. table:: Return values
+
+        ===== =============================================
+        Value      Meaning
+        ===== =============================================
+        > 0   The version *a* is greater than version *b*.
+        = 0   Both versions are equal.
+        < 0   The version *a* is less than version *b*.
+        ===== =============================================
 
 
 Data
@@ -256,6 +375,18 @@ Select states
 Build information
 ^^^^^^^^^^^^^^^^^
 .. data:: Date
+
+    The date on which this extension has been compiled.
+
 .. data:: LibVersion
+
+    The version of the apt_pkg library. This is **not** the version of apt,
+    nor the version of python-apt.
+
 .. data:: Time
+
+    The time this extension has been built.
+
 .. data:: Version
+
+    The version of apt (not of python-apt).
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 8f71e3e3..3b0ebed7 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -59,7 +59,7 @@ copyright = u'2009, Julian Andres Klode <jak@debian.org>'
 # The short X.Y version.
 version = '0.7'
 # The full version, including alpha/beta/rc tags.
-release = '0.7.9~exp2'
+release = '0.7.9~exp3'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.