Fix rst docs

5 files changed, 134 insertions, 119 deletions

diff --git a/doc/callbacks.rst b/doc/callbacks.rst
index fca89b7..1f74873 100644
--- a/doc/callbacks.rst
+++ b/doc/callbacks.rst
@@ -22,27 +22,28 @@ instance attributes to store per object data such as files used in the
 callbacks.
 
 The signature of each callback used in pycurl is as follows:
-> <br> ``WRITEFUNCTION(``*string*``) ``*-> number of characters written
-> <em>
-> <code>READFUNCTION(<code>*number of characters to read*``)``*-> string*
-> <br> ``HEADERFUNCTION(``*string*``)``* -> number of characters written
-> <em>
-> <code>PROGRESSFUNCTION(<code>*download total, downloaded, upload total,
-uploaded*``) ``*-> status*
-> <br> ``DEBUGFUNCTION(``*debug message type, debug message string*``)`` *->
-None
-><em>
-> <code>IOCTLFUNCTION(<code>*ioctl cmd*``)`` *-> status
-><em>
-> <p>In addition, <code>READFUNCTION<code> may return ``READFUNC_ABORT`` or
+
+``WRITEFUNCTION(``*string*``) `` -> *number of characters written*
+
+``READFUNCTION(``*number of characters to read*``)`` -> *string*
+
+``HEADERFUNCTION(``*string*``)`` -> *number of characters written*
+
+``PROGRESSFUNCTION(``*download total, downloaded, upload total,
+uploaded*``) `` -> *status*
+
+``DEBUGFUNCTION(``*debug message type, debug message string*``)`` -> *None*
+
+``IOCTLFUNCTION(``*ioctl cmd*``)`` -> *status*
+
+In addition, ``READFUNCTION`` may return ``READFUNC_ABORT`` or
 ``READFUNC_PAUSE``. See the libcurl documentation for an explanation of these
 values. The ``WRITEFUNCTION`` and ``HEADERFUNCTION`` callbacks may return
 ``None``, which is an alternate way of indicating that the callback has
 consumed all of the string passed to it.
 
---------
-
-> <h2>Example: Callbacks for document header and body<h2>
+Example: Callbacks for document header and body
+-----------------------------------------------
 
 This example prints the header data to stderr and the body data to stdout.
 Also note that neither callback returns the number of bytes written. For
@@ -50,25 +51,26 @@ WRITEFUNCTION and HEADERFUNCTION callbacks, returning None implies that all
 bytes where written.
 
 ::
-        ## Callback function invoked when body data is ready
-        def body(buf):
-            # Print body data to stdout
-            import sys
-            sys.stdout.write(buf)
-            # Returning None implies that all bytes were written
-
-        ## Callback function invoked when header data is ready
-        def header(buf):
-            # Print header data to stderr
-            import sys
-            sys.stderr.write(buf)
-            # Returning None implies that all bytes were written
-
-        c = pycurl.Curl()
-        c.setopt(pycurl.URL, "http://www.python.org/")
-        c.setopt(pycurl.WRITEFUNCTION, body)
-        c.setopt(pycurl.HEADERFUNCTION, header)
-        c.perform()
+
+    ## Callback function invoked when body data is ready
+    def body(buf):
+        # Print body data to stdout
+        import sys
+        sys.stdout.write(buf)
+        # Returning None implies that all bytes were written
+
+    ## Callback function invoked when header data is ready
+    def header(buf):
+        # Print header data to stderr
+        import sys
+        sys.stderr.write(buf)
+        # Returning None implies that all bytes were written
+
+    c = pycurl.Curl()
+    c.setopt(pycurl.URL, "http://www.python.org/")
+    c.setopt(pycurl.WRITEFUNCTION, body)
+    c.setopt(pycurl.HEADERFUNCTION, header)
+    c.perform()
 
 Example: Download/upload progress callback
 ------------------------------------------
@@ -77,18 +79,19 @@ This example shows how to use the progress callback. When downloading a
 document, the arguments related to uploads are zero, and vice versa.
 
 ::
-        ## Callback function invoked when download/upload has
-        progress
-        def progress(download_t, download_d, upload_t, upload_d):
-            print "Total to download", download_t
-            print "Total downloaded", download_d
-            print "Total to upload", upload_t
-            print "Total uploaded", upload_d
-
-        c.setopt(c.URL, "http://slashdot.org/")
-        c.setopt(c.NOPROGRESS, 0)
-        c.setopt(c.PROGRESSFUNCTION, progress)
-        c.perform()
+
+    ## Callback function invoked when download/upload has
+    progress
+    def progress(download_t, download_d, upload_t, upload_d):
+        print "Total to download", download_t
+        print "Total downloaded", download_d
+        print "Total to upload", upload_t
+        print "Total uploaded", upload_d
+
+    c.setopt(c.URL, "http://slashdot.org/")
+    c.setopt(c.NOPROGRESS, 0)
+    c.setopt(c.PROGRESSFUNCTION, progress)
+    c.perform()
 
 Example: Debug callbacks
 ------------------------
@@ -98,14 +101,15 @@ an integer indicating the type of debug message. The VERBOSE option must be
 enabled for this callback to be invoked.
 
 ::
-        def test(debug_type, debug_msg):
-            print "debug(%d): %s" % (debug_type, debug_msg)
-
-        c = pycurl.Curl()
-        c.setopt(pycurl.URL, "http://curl.haxx.se/")
-        c.setopt(pycurl.VERBOSE, 1)
-        c.setopt(pycurl.DEBUGFUNCTION, test)
-        c.perform()
+
+    def test(debug_type, debug_msg):
+        print "debug(%d): %s" % (debug_type, debug_msg)
+
+    c = pycurl.Curl()
+    c.setopt(pycurl.URL, "http://curl.haxx.se/")
+    c.setopt(pycurl.VERBOSE, 1)
+    c.setopt(pycurl.DEBUGFUNCTION, test)
+    c.perform()
 
 Other examples
 --------------
diff --git a/doc/curlmultiobject.rst b/doc/curlmultiobject.rst
index 8d5aaec..7c4c181 100644
--- a/doc/curlmultiobject.rst
+++ b/doc/curlmultiobject.rst
@@ -5,17 +5,17 @@ CurlMulti objects have the following methods:
 
 ``close()`` -> *None*
 
-Corresponds to ```curl_multi_cleanup()```_ in libcurl. This method is
+Corresponds to `curl_multi_cleanup`_ in libcurl. This method is
 automatically called by pycurl when a CurlMulti object no longer has any
 references to it, but can also be called explicitly.
 
 ``perform()`` -> *tuple of status and the number of active Curl objects*
 
-Corresponds to ```curl_multi_perform()```_ in libcurl.
+Corresponds to `curl_multi_perform`_ in libcurl.
 
-``add_handle(``*Curl object*``) ``-> *None*
+``add_handle(``*Curl object*``) `` -> *None*
 
-Corresponds to ```curl_multi_add_handle()```_ in libcurl. This method adds an
+Corresponds to `curl_multi_add_handle`_ in libcurl. This method adds an
 existing and valid Curl object to the CurlMulti object.
 
 IMPORTANT NOTE: add_handle does not implicitly add a Python reference to the
@@ -24,7 +24,7 @@ object).
 
 ``remove_handle(``*Curl object*``)`` -> *None*
 
-Corresponds to ```curl_multi_remove_handle()```_ in libcurl. This method
+Corresponds to `curl_multi_remove_handle`_ in libcurl. This method
 removes an existing and valid Curl object from the CurlMulti object.
 
 IMPORTANT NOTE: remove_handle does not implicitly remove a Python reference
@@ -34,13 +34,14 @@ Curl object).
 ``fdset()`` -> *triple of lists with active file descriptors, readable,
 writeable, exceptions.*
 
-Corresponds to ```curl_multi_fdset()```_ in libcurl. This method extracts the
+Corresponds to `curl_multi_fdset`_ in libcurl. This method extracts the
 file descriptor information from a CurlMulti object. The returned lists can
 be used with the ``select`` module to poll for events.
 
 Example usage:
 
 ::
+
     import pycurl
     c = pycurl.Curl()
     c.setopt(pycurl.URL, "http://curl.haxx.se")
@@ -54,15 +55,17 @@ Example usage:
         while 1:
             ret, num_handles = m.perform()
             if ret != pycurl.E_CALL_MULTI_PERFORM: break
-     ``select(``*timeout*``)`` -> *number of ready file descriptors or
-     -1 on timeout*
+
+``select(``*timeout*``)`` -> *number of ready file descriptors or -1 on timeout*
 
 This is a convenience function which simplifies the combined use of
 ``fdset()`` and the ``select`` module.
 
 Example usage:
 
-::import pycurl
+::
+
+    import pycurl
     c = pycurl.Curl()
     c.setopt(pycurl.URL, "http://curl.haxx.se")
     m = pycurl.CurlMulti()
@@ -76,25 +79,26 @@ Example usage:
         while 1:
             ret, num_handles = m.perform()
             if ret != pycurl.E_CALL_MULTI_PERFORM: break
-     ``info_read(``*[max]*``)`` -> *numberof queued messages, a list of
-     successful objects, a list of failed objects*
 
-Corresponds to the ```curl_multi_info_read()```_ function in libcurl. This
+``info_read(``*[max]*``)`` -> *number of queued messages, a list of
+successful objects, a list of failed objects*
+
+Corresponds to the `curl_multi_info_read`_ function in libcurl. This
 method extracts at most *max* messages from the multi stack and returns them
 in two lists. The first list contains the handles which completed
-successfully and the second list contains a tuple *<curl object, curl error
-number, curl error message>* for each failed curl object. The number of
+successfully and the second list contains a tuple *(curl object, curl error
+number, curl error message)* for each failed curl object. The number of
 queued messages after this method has been called is also returned.
 
-.. _curl_multi_cleanup():
+.. _curl_multi_cleanup:
     http://curl.haxx.se/libcurl/c/curl_multi_cleanup.html
-.. _curl_multi_perform():
+.. _curl_multi_perform:
     http://curl.haxx.se/libcurl/c/curl_multi_perform.html
-.. _curl_multi_add_handle():
+.. _curl_multi_add_handle:
     http://curl.haxx.se/libcurl/c/curl_multi_add_handle.html
-.. _curl_multi_remove_handle():
+.. _curl_multi_remove_handle:
     http://curl.haxx.se/libcurl/c/curl_multi_remove_handle.html
-.. _curl_multi_fdset():
+.. _curl_multi_fdset:
     http://curl.haxx.se/libcurl/c/curl_multi_fdset.html
-.. _curl_multi_info_read():
+.. _curl_multi_info_read:
     http://curl.haxx.se/libcurl/c/curl_multi_info_read.html
diff --git a/doc/curlobject.rst b/doc/curlobject.rst
index d6cb95d..187a845 100644
--- a/doc/curlobject.rst
+++ b/doc/curlobject.rst
@@ -5,22 +5,23 @@ Curl objects have the following methods:
 
 ``close()`` -> *None*
 
-Corresponds to ```curl_easy_cleanup```_ in libcurl. This method is
+Corresponds to `curl_easy_cleanup`_ in libcurl. This method is
 automatically called by pycurl when a Curl object no longer has any
 references to it, but can also be called explicitly.
 
 ``perform()`` -> *None*
 
-Corresponds to ```curl_easy_perform```_ in libcurl.
+Corresponds to `curl_easy_perform`_ in libcurl.
 
 ``reset()`` -> *None*
 
-Corresponds to ```curl_easy_reset```_ in libcurl.
+Corresponds to `curl_easy_reset`_ in libcurl.
 
 ``setopt(``*option, value*``)`` -> *None*
 
-Corresponds to ```curl_easy_setopt```_ in libcurl, where *option* is
-specified with the CURLOPT_* constants in libcurl, except that the CURLOPT_
+Corresponds to `curl_easy_setopt`_ in libcurl, where *option* is
+specified with the ``CURLOPT_*`` constants in libcurl, except that the
+``CURLOPT_``
 prefix has been removed. (See below for exceptions.) The type for *value*
 depends on the option, and can be either a string, integer, long integer,
 file object, list, or function.
@@ -28,6 +29,7 @@ file object, list, or function.
 Example usage:
 
 ::
+
     import pycurl
     c = pycurl.Curl()
     c.setopt(pycurl.URL, "http://www.python.org/")
@@ -40,10 +42,12 @@ Example usage:
     c.perform()
     print b.getvalue()
     ...
-     ``getinfo(``*option*``) ``-> *Result*
 
-Corresponds to ```curl_easy_getinfo```_ in libcurl, where *option* is the
-same as the CURLINFO_* constants in libcurl, except that the CURLINFO_ prefix
+``getinfo(``*option*``) `` -> *Result*
+
+Corresponds to `curl_easy_getinfo`_ in libcurl, where *option* is the
+same as the ``CURLINFO_*`` constants in libcurl, except that the ``CURLINFO_``
+prefix
 has been removed. (See below for exceptions.) *Result* contains an integer,
 float or string, depending on which option is given. The ``getinfo`` method
 should not be called unless ``perform`` has been called and finished.
@@ -51,6 +55,7 @@ should not be called unless ``perform`` has been called and finished.
 Example usage:
 
 ::
+
     import pycurl
     c = pycurl.Curl()
     c.setopt(pycurl.URL, "http://sf.net")
@@ -59,9 +64,10 @@ Example usage:
     print c.getinfo(pycurl.HTTP_CODE), c.getinfo(pycurl.EFFECTIVE_URL)
     ...
     --> 200 "http://sourceforge.net/"
-     ``pause(``*bitmask*``) ``-> *None*
 
-Corresponds to ```curl_easy_pause```_ in libcurl. The argument should be
+``pause(``*bitmask*``) `` -> *None*
+
+Corresponds to `curl_easy_pause`_ in libcurl. The argument should be
 derived from the ``PAUSE_RECV``, ``PAUSE_SEND``, ``PAUSE_ALL`` and
 ``PAUSE_CONT`` constants.
 
diff --git a/doc/curlshareobject.rst b/doc/curlshareobject.rst
index ba0434b..d474b06 100644
--- a/doc/curlshareobject.rst
+++ b/doc/curlshareobject.rst
@@ -5,14 +5,15 @@ CurlShare objects have the following methods:
 
 ``setopt(``*option, value*``)`` -> *None*
 
-Corresponds to ```curl_share_setopt```_ in libcurl, where *option* is
-specified with the CURLSHOPT_* constants in libcurl, except that the
-CURLSHOPT_ prefix has been changed to SH_. Currently, *value* must be either
-LOCK_DATA_COOKIE or LOCK_DATA_DNS.
+Corresponds to `curl_share_setopt`_ in libcurl, where *option* is
+specified with the ``CURLSHOPT_*`` constants in libcurl, except that the
+``CURLSHOPT_`` prefix has been changed to ``SH_``. Currently, *value* must be
+either ``LOCK_DATA_COOKIE`` or ``LOCK_DATA_DNS``.
 
 Example usage:
 
 ::
+
     import pycurl
     curl = pycurl.Curl()
     s = pycurl.CurlShare()
diff --git a/doc/pycurl.rst b/doc/pycurl.rst
index 13bbdd3..295a7e9 100644
--- a/doc/pycurl.rst
+++ b/doc/pycurl.rst
@@ -1,9 +1,9 @@
 ``PycURL`` -- A Python Interface To The cURL library
 ====================================================
 
-The pycurl package is a Python interface to libcurl
-(`http://curl.haxx.se/libcurl/`_). pycurl has been successfully built and
-tested with Python versions from 2.4 to 2.7.
+The pycurl package is a Python interface to `libcurl`_.
+pycurl has been successfully built and
+tested with Python versions from 2.4 to 2.7 and 3.1 to 3.3.
 
 libcurl is a client-side URL transfer library supporting FTP, FTPS, HTTP,
 HTTPS, GOPHER, TELNET, DICT, FILE and LDAP. libcurl also supports HTTPS
@@ -14,49 +14,52 @@ and more.
 All the functionality provided by libcurl can used through the pycurl
 interface. The following subsections describe how to use the pycurl
 interface, and assume familiarity with how libcurl works. For information on
-how libcurl works, please consult the curl library web pages
-(`http://curl.haxx.se/libcurl/c/`_).
+how libcurl works, please consult the `curl library C API`_.
 
---------
+Module Functionality
+--------------------
 
-> <h1>Module Functionality<h1>  ``pycurl.global_init(``*option*``)`` ->*None*
+``pycurl.global_init(``*option*``)`` ->*None*
 
 *option* is one of the constants pycurl.GLOBAL_SSL, pycurl.GLOBAL_WIN32,
 pycurl.GLOBAL_ALL, pycurl.GLOBAL_NOTHING, pycurl.GLOBAL_DEFAULT. Corresponds
-to ```curl_global_init()```_ in libcurl.
+to `curl_global_init`_ in libcurl.
 
 ``pycurl.global_cleanup()`` -> *None*
 
-Corresponds to ```curl_global_cleanup()```_ in libcurl.
+Corresponds to `curl_global_cleanup`_ in libcurl.
 
 ``pycurl.version``
 
 This is a string with version information on libcurl, corresponding to
-```curl_version()```_ in libcurl.
+`curl_version`_ in libcurl.
 
 Example usage:
 
 ::
+
     >>> import pycurl
     >>> pycurl.version
-    'libcurl/7.12.3 OpenSSL/0.9.7e zlib/1.2.2.1 libidn/0.5.12'
-     ``pycurl.version_info()`` -> *Tuple*
+    'PycURL/7.19.3 libcurl/7.33.0 OpenSSL/0.9.8x zlib/1.2.7'
+
+``pycurl.version_info()`` -> *Tuple*
 
-Corresponds to ```curl_version_info()```_ in libcurl. Returns a tuple of
+Corresponds to `curl_version_info`_ in libcurl. Returns a tuple of
 information which is similar to the ``curl_version_info_data`` struct
 returned by ``curl_version_info()`` in libcurl.
 
 Example usage:
 
 ::
+
     >>> import pycurl
     >>> pycurl.version_info()
-    (2, '7.12.3', 461827, 'i586-pc-linux-gnu', 1565, 'OpenSSL/0.9.7e',
-    9465951,
-    '1.2.2.1', ('ftp', 'gopher', 'telnet', 'dict', 'ldap', 'http',
-    'file',
-    'https', 'ftps'), None, 0, '0.5.12')
-     ``pycurl.Curl()`` -> *Curl object*
+    (3, '7.33.0', 467200, 'amd64-portbld-freebsd9.1', 33436, 'OpenSSL/0.9.8x',
+    0, '1.2.7', ('dict', 'file', 'ftp', 'ftps', 'gopher', 'http', 'https',
+    'imap', 'imaps', 'pop3', 'pop3s', 'rtsp', 'smtp', 'smtps', 'telnet',
+    'tftp'), None, 0, None)
+
+``pycurl.Curl()`` -> *Curl object*
 
 This function creates a new `Curl object`_ which corresponds to a ``CURL``
 handle in libcurl. Curl objects automatically set CURLOPT_VERBOSE to 0,
@@ -74,9 +77,9 @@ This function creates a new `CurlShare object`_ which corresponds to a
 ``CURLSH`` handle in libcurl. CurlShare objects is what you pass as an
 argument to the SHARE option on Curl objects.
 
---------
 
-> <h1>Subsections<h1>
+Subsections
+-----------
 
 -   `Curl objects`_
 -   `CurlMulti objects`_
@@ -92,15 +95,12 @@ Documentation For Developers
 -   `Notes on PycURL internals`_
 -   `Release process`_
 
-.. _http://curl.haxx.se/libcurl/: http://curl.haxx.se/libcurl/
-.. _http://curl.haxx.se/libcurl/c/: http://curl.haxx.se/libcurl/c/
-.. _curl_global_init():
-    http://curl.haxx.se/libcurl/c/curl_global_init.html
-.. _curl_global_cleanup():
-    http://curl.haxx.se/libcurl/c/curl_global_cleanup.html
-.. _curl_version(): http://curl.haxx.se/libcurl/c/curl_version.html
-.. _curl_version_info():
-    http://curl.haxx.se/libcurl/c/curl_version_info.html
+.. _libcurl: http://curl.haxx.se/libcurl/
+.. _curl library C API: http://curl.haxx.se/libcurl/c/
+.. _curl_global_init: http://curl.haxx.se/libcurl/c/curl_global_init.html
+.. _curl_global_cleanup: http://curl.haxx.se/libcurl/c/curl_global_cleanup.html
+.. _curl_version: http://curl.haxx.se/libcurl/c/curl_version.html
+.. _curl_version_info: http://curl.haxx.se/libcurl/c/curl_version_info.html
 .. _Curl object: curlobject.html
 .. _Curl objects: curlobject.html
 .. _CurlMulti object: curlmultiobject.html