Merge pull request #152 from p-push/rst-docs

Convert documentation to restructured text
author: Oleg Pudeyev <oleg@bsdpower.com> 2014-01-16 20:41:22 -0800
committer: Oleg Pudeyev <oleg@bsdpower.com> 2014-01-16 20:41:22 -0800
commit: 5576e7909deb123856da3debc6caf6314c4a771a (patch)
tree: f9e834eeb3a7b2901bc24584963fb2d33d10eda1
parent: f3d35fb0a5494c7e1d4c9ac49157bd3360773a94 (diff)
parent: 77757d8427979aac1600ef699bb6d4e6db4a2107 (diff)
download: pycurl-5576e7909deb123856da3debc6caf6314c4a771a.tar.gz
12 files changed, 466 insertions, 608 deletions
diff --git a/MANIFEST.in b/MANIFEST.in
index 25f8ffa..d2ddfac 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -11,7 +11,6 @@ include MANIFEST.in
 include Makefile
 include README.rst
 include RELEASE-NOTES.rst
-include doc/*.html
 include doc/*.rst
 include examples/*.py
 include examples/tests/*.py
diff --git a/doc/callbacks.html b/doc/callbacks.html
deleted file mode 100644
index 83b1445..0000000
--- a/doc/callbacks.html
+++ /dev/null
@@ -1,147 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
-    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
-  <title>PyCurl: Callbacks</title>
-  <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
-  <meta name="revisit-after" content="30 days" />
-  <meta name="robots" content="noarchive, index, follow" />
-</head>
-<body>
-
-<h1>Callbacks</h1>
-
-<p>For more fine-grained control, libcurl allows a
-number of callbacks to be associated with each connection. In
-pycurl, callbacks are defined using the <code>setopt()</code> method for
-Curl objects with options WRITEFUNCTION, READFUNCTION, HEADERFUNCTION,
-PROGRESSFUNCTION, IOCTLFUNCTION, or DEBUGFUNCTION. These options
-correspond to the libcurl options with CURLOPT_* prefix removed.  A
-callback in pycurl must be either a regular Python function, a class
-method or an extension type function.</p>
-
-<p>There are some limitations to some of the options which can be used
-concurrently with the pycurl callbacks compared to the libcurl callbacks.
-This is to allow different callback functions to be associated with
-different Curl objects.  More specifically, WRITEDATA cannot
-be used with WRITEFUNCTION, READDATA cannot be used with READFUNCTION,
-WRITEHEADER cannot be used with HEADERFUNCTION, PROGRESSDATA cannot be
-used with PROGRESSFUNCTION, IOCTLDATA cannot be used with IOCTLFUNCTION,
-and DEBUGDATA cannot be used with DEBUGFUNCTION.
-In practice, these limitations can be overcome by having a callback
-function be a class instance method and rather use the class instance
-attributes to store per object data such as files used in the callbacks.
-</p>
-
-The signature of each callback used in pycurl is as follows:<br/>
-<br/>
-<code>WRITEFUNCTION(</code><em>string</em><code>) </code><em>-&gt; number of characters written<br/>
-</em>
-<br/>
-<code>READFUNCTION(</code><em>number of characters to read</em><code>)</code><em>-&gt;
-string</em><br/>
-<br/>
-<code>HEADERFUNCTION(</code><em>string</em><code>)</code><em> -&gt; number of characters written<br/>
-</em><br/>
-<code>PROGRESSFUNCTION(</code><em>download total, downloaded, upload total, uploaded</em><code>) </code><em>-&gt; status</em><br/>
-<br/>
-<code>DEBUGFUNCTION(</code><em>debug message type, debug message string</em><code>)</code>
-<em>-&gt; None<br/></em>
-<br/>
-<code>IOCTLFUNCTION(</code><em>ioctl cmd</em><code>)</code>
-<em>-&gt; status<br/></em>
-<br/>
-
-<p>In addition, <code>READFUNCTION</code> may return
-<code>READFUNC_ABORT</code> or <code>READFUNC_PAUSE</code>. See the libcurl
-documentation for an explanation of these values.
-The <code>WRITEFUNCTION</code> and <code>HEADERFUNCTION</code> callbacks
-may return <code>None</code>, which is an alternate way of indicating that
-the callback has consumed all of the string passed to it.</p>
-
-<hr/>
-
-<h2>Example: Callbacks for document header and body</h2>
-
-<p>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 WRITEFUNCTION and HEADERFUNCTION callbacks, returning
-None implies that all bytes where written.</p>
-
-<pre>
-    ## 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()
-</pre>
-
-<h2>Example: Download/upload progress callback</h2>
-
-<p>This example shows how to use the progress callback.  When downloading
-a document, the arguments related to uploads are zero, and vice versa.</p>
-
-<pre>
-    ## 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()
-</pre>
-
-<h2>Example: Debug callbacks</h2>
-
-<p>This example shows how to use the debug callback.  The debug message
-type is an integer indicating the type of debug message.  The
-VERBOSE option must be enabled for this callback to be invoked.</p>
-
-<pre>
-    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()
-</pre>
-
-<h2>Other examples</h2>
-<p>The pycurl distribution also contains a number of test scripts and
-examples which show how to use the various callbacks in libcurl.
-For instance, the file 'examples/file_upload.py' in the distribution contains
-example code for using READFUNCTION, 'tests/test_cb.py' shows
-WRITEFUNCTION and HEADERFUNCTION, 'tests/test_debug.py' shows DEBUGFUNCTION,
-and 'tests/test_getinfo.py' shows PROGRESSFUNCTION.</p>
-
-
-<hr />
-<p>
-  <a href="http://validator.w3.org/check/referer"><img align="right"
-     src="http://www.w3.org/Icons/valid-xhtml10"
-     alt="Valid XHTML 1.0!" height="31" width="88" border="0" /></a>
-</p>
-
-</body>
-</html>
diff --git a/doc/callbacks.rst b/doc/callbacks.rst
new file mode 100644
index 0000000..bfe1835
--- /dev/null
+++ b/doc/callbacks.rst
@@ -0,0 +1,122 @@
+Callbacks
+=========
+
+For more fine-grained control, libcurl allows a number of callbacks to be
+associated with each connection. In pycurl, callbacks are defined using the
+``setopt()`` method for Curl objects with options WRITEFUNCTION,
+READFUNCTION, HEADERFUNCTION, PROGRESSFUNCTION, IOCTLFUNCTION, or
+DEBUGFUNCTION. These options correspond to the libcurl options with CURLOPT_*
+prefix removed. A callback in pycurl must be either a regular Python
+function, a class method or an extension type function.
+
+There are some limitations to some of the options which can be used
+concurrently with the pycurl callbacks compared to the libcurl callbacks.
+This is to allow different callback functions to be associated with different
+Curl objects. More specifically, WRITEDATA cannot be used with WRITEFUNCTION,
+READDATA cannot be used with READFUNCTION, WRITEHEADER cannot be used with
+HEADERFUNCTION, PROGRESSDATA cannot be used with PROGRESSFUNCTION, IOCTLDATA
+cannot be used with IOCTLFUNCTION, and DEBUGDATA cannot be used with
+DEBUGFUNCTION. In practice, these limitations can be overcome by having a
+callback function be a class instance method and rather use the class
+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:
+
+**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.
+
+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
+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()
+
+Example: Download/upload progress callback
+------------------------------------------
+
+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()
+
+Example: Debug callbacks
+------------------------
+
+This example shows how to use the debug callback. The debug message type is
+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()
+
+Other examples
+--------------
+
+The pycurl distribution also contains a number of test scripts and examples
+which show how to use the various callbacks in libcurl. For instance, the
+file 'examples/file_upload.py' in the distribution contains example code for
+using READFUNCTION, 'tests/test_cb.py' shows WRITEFUNCTION and
+HEADERFUNCTION, 'tests/test_debug.py' shows DEBUGFUNCTION, and
+'tests/test_getinfo.py' shows PROGRESSFUNCTION.
diff --git a/doc/curlmultiobject.html b/doc/curlmultiobject.html
deleted file mode 100644
index f14827c..0000000
--- a/doc/curlmultiobject.html
+++ /dev/null
@@ -1,135 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
-    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
-  <title>PycURL: CurlMulti Objects</title>
-  <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
-  <meta name="revisit-after" content="30 days" />
-  <meta name="robots" content="noarchive, index, follow" />
-</head>
-<body>
-
-<h1>CurlMulti Object</h1>
-
-<p>CurlMulti objects have the following methods: </p>
-
-<dl>
-<dt><code>close()</code> -&gt; <em>None</em></dt>
-<dd>
-<p>Corresponds to
-<a href="http://curl.haxx.se/libcurl/c/curl_multi_cleanup.html"><code>curl_multi_cleanup()</code></a> 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.</p>
-</dd>
-
-<dt><code>perform()</code> -&gt; <em>tuple of status and the number of active Curl objects</em></dt>
-<dd>
-<p>Corresponds to
-<a href="http://curl.haxx.se/libcurl/c/curl_multi_perform.html"><code>curl_multi_perform()</code></a> in libcurl.</p>
-</dd>
-
-<dt><code>add_handle(</code><em>Curl object</em><code>) </code>-&gt; <em>None</em></dt>
-<dd>
-<p>Corresponds to
-<a href="http://curl.haxx.se/libcurl/c/curl_multi_add_handle.html"><code>curl_multi_add_handle()</code></a> in libcurl.
-This method  adds an existing and valid Curl object to the CurlMulti
-object.</p>
-
-<p>IMPORTANT NOTE: add_handle does not implicitly add a Python reference
-to the Curl object (and thus does not increase the reference count on the Curl
-object).</p>
-</dd>
-
-<dt><code>remove_handle(</code><em>Curl object</em><code>)</code> -&gt; <em>None</em></dt>
-<dd>
-<p>Corresponds to
-<a href="http://curl.haxx.se/libcurl/c/curl_multi_remove_handle.html"><code>curl_multi_remove_handle()</code></a> in libcurl.
-This method removes an existing and valid Curl object from the CurlMulti
-object.</p>
-
-<p>IMPORTANT NOTE: remove_handle does not implicitly remove a Python reference
-from the Curl object (and thus does not decrease the reference count on the Curl
-object).</p>
-</dd>
-
-<dt><code>fdset()</code> -&gt;
-<em>triple of lists with active file descriptors,
-readable,  writeable, exceptions.</em></dt>
-<dd>
-<p>Corresponds to
-<a href="http://curl.haxx.se/libcurl/c/curl_multi_fdset.html"><code>curl_multi_fdset()</code></a> in libcurl.
-This method extracts  the file descriptor information from a CurlMulti object.
-The returned  lists can be used with the <code>select</code> module to
-poll for events.</p>
-
-<p>Example usage:</p>
-
-<pre>
-import pycurl
-c = pycurl.Curl()
-c.setopt(pycurl.URL, "http://curl.haxx.se")
-m = pycurl.CurlMulti()
-m.add_handle(c)
-while 1:
-    ret, num_handles = m.perform()
-    if ret != pycurl.E_CALL_MULTI_PERFORM: break
-while num_handles:
-    apply(select.select, m.fdset() + (1,))
-    while 1:
-        ret, num_handles = m.perform()
-        if ret != pycurl.E_CALL_MULTI_PERFORM: break
-</pre>
-</dd>
-
-<dt><code>select(</code><em>timeout</em><code>)</code> -&gt;
-<em>number of ready file descriptors or -1 on timeout</em></dt>
-<dd>
-<p>This is a convenience function which simplifies the combined
-use of <code>fdset()</code> and the <code>select</code> module.</p>
-
-<p>Example usage:</p>
-
-<pre>import pycurl
-c = pycurl.Curl()
-c.setopt(pycurl.URL, "http://curl.haxx.se")
-m = pycurl.CurlMulti()
-m.add_handle(c)
-while 1:
-    ret, num_handles = m.perform()
-    if ret != pycurl.E_CALL_MULTI_PERFORM: break
-while num_handles:
-    ret = m.select(1.0)
-    if ret == -1:  continue
-    while 1:
-        ret, num_handles = m.perform()
-        if ret != pycurl.E_CALL_MULTI_PERFORM: break
-</pre>
-</dd>
-
-<dt><code>info_read(</code><em>[max]</em><code>)</code> -&gt;
-<em>numberof queued messages, a list of successful objects, a list of
-failed objects</em></dt>
-<dd>
-<p>Corresponds to the
-<a href="http://curl.haxx.se/libcurl/c/curl_multi_info_read.html"><code>curl_multi_info_read()</code></a> function in libcurl.
-This method extracts at most <em>max</em> 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 <em>&lt;curl object, curl error number, curl
-error message&gt;</em> for each failed curl object. The number
-of queued messages after this method has been called is also
-returned.</p>
-</dd>
-</dl>
-
-<hr />
-<p>
-  <a href="http://validator.w3.org/check/referer"><img align="right"
-     src="http://www.w3.org/Icons/valid-xhtml10"
-     alt="Valid XHTML 1.0!" height="31" width="88" border="0" /></a>
-</p>
-
-</body>
-</html>
diff --git a/doc/curlmultiobject.rst b/doc/curlmultiobject.rst
new file mode 100644
index 0000000..f09a8c3
--- /dev/null
+++ b/doc/curlmultiobject.rst
@@ -0,0 +1,104 @@
+CurlMulti Object
+================
+
+CurlMulti objects have the following methods:
+
+**close**\ () -> *None*
+
+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.
+
+**add_handle**\ (*Curl object*)  -> *None*
+
+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
+Curl object (and thus does not increase the reference count on the Curl
+object).
+
+**remove_handle**\ (*Curl object*) -> *None*
+
+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
+from the Curl object (and thus does not decrease the reference count on the
+Curl object).
+
+**fdset**\ () -> *triple of lists with active file descriptors, readable,
+writeable, exceptions.*
+
+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")
+    m = pycurl.CurlMulti()
+    m.add_handle(c)
+    while 1:
+        ret, num_handles = m.perform()
+        if ret != pycurl.E_CALL_MULTI_PERFORM: break
+    while num_handles:
+        apply(select.select, m.fdset() + (1,))
+        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*
+
+This is a convenience function which simplifies the combined use of
+``fdset()`` and the ``select`` module.
+
+Example usage:
+
+::
+
+    import pycurl
+    c = pycurl.Curl()
+    c.setopt(pycurl.URL, "http://curl.haxx.se")
+    m = pycurl.CurlMulti()
+    m.add_handle(c)
+    while 1:
+        ret, num_handles = m.perform()
+        if ret != pycurl.E_CALL_MULTI_PERFORM: break
+    while num_handles:
+        ret = m.select(1.0)
+        if ret == -1:  continue
+        while 1:
+            ret, num_handles = m.perform()
+            if ret != pycurl.E_CALL_MULTI_PERFORM: break
+
+**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
+queued messages after this method has been called is also returned.
+
+.. _curl_multi_cleanup:
+    http://curl.haxx.se/libcurl/c/curl_multi_cleanup.html
+.. _curl_multi_perform:
+    http://curl.haxx.se/libcurl/c/curl_multi_perform.html
+.. _curl_multi_add_handle:
+    http://curl.haxx.se/libcurl/c/curl_multi_add_handle.html
+.. _curl_multi_remove_handle:
+    http://curl.haxx.se/libcurl/c/curl_multi_remove_handle.html
+.. _curl_multi_fdset:
+    http://curl.haxx.se/libcurl/c/curl_multi_fdset.html
+.. _curl_multi_info_read:
+    http://curl.haxx.se/libcurl/c/curl_multi_info_read.html
diff --git a/doc/curlobject.html b/doc/curlobject.html
deleted file mode 100644
index 0de0730..0000000
--- a/doc/curlobject.html
+++ /dev/null
@@ -1,132 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
-    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
-  <title>PycURL: Curl Objects</title>
-  <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
-  <meta name="revisit-after" content="30 days" />
-  <meta name="robots" content="noarchive, index, follow" />
-</head>
-<body>
-
-<h1>Curl Object</h1>
-
-<p>Curl objects have the following methods:</p>
-
-<dl>
-<dt><code>close()</code> -&gt; <em>None</em></dt>
-<dd>
-<p>Corresponds to
-<a href="http://curl.haxx.se/libcurl/c/curl_easy_cleanup.html"><code>curl_easy_cleanup</code></a> 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.</p>
-</dd>
-
-<dt><code>perform()</code> -&gt; <em>None</em></dt>
-<dd>
-<p>Corresponds to
-<a href="http://curl.haxx.se/libcurl/c/curl_easy_perform.html"><code>curl_easy_perform</code></a> in libcurl.</p>
-</dd>
-
-<dt><code>reset()</code> -&gt; <em>None</em></dt>
-<dd>
-<p>Corresponds to
-<a
-href="http://curl.haxx.se/libcurl/c/curl_easy_reset.html"><code>curl_easy_reset</code></a> in libcurl.</p>
-</dd>
-
-
-<dt><code>setopt(</code><em>option, value</em><code>)</code> -&gt; <em>None</em></dt>
-<dd>
-
-<p>Corresponds to
-<a href="http://curl.haxx.se/libcurl/c/curl_easy_setopt.html"><code>curl_easy_setopt</code></a> in libcurl, where
-<em>option</em> is specified with the CURLOPT_* constants in libcurl,
-except that the CURLOPT_ prefix has been removed.
-(See below for exceptions.)
-The type for
-<em>value</em> depends on the option, and can be either a string,
-integer, long integer, file object, list, or function.</p>
-
-<p>Example usage:</p>
-
-<pre>
-import pycurl
-c = pycurl.Curl()
-c.setopt(pycurl.URL, "http://www.python.org/")
-c.setopt(pycurl.HTTPHEADER, ["Accept:"])
-import StringIO
-b = StringIO.StringIO()
-c.setopt(pycurl.WRITEFUNCTION, b.write)
-c.setopt(pycurl.FOLLOWLOCATION, 1)
-c.setopt(pycurl.MAXREDIRS, 5)
-c.perform()
-print b.getvalue()
-...
-</pre>
-</dd>
-
-<dt><code>getinfo(</code><em>option</em><code>) </code>-&gt; <em>Result</em></dt>
-<dd>
-
-<p>Corresponds to
-<a href="http://curl.haxx.se/libcurl/c/curl_easy_getinfo.html"><code>curl_easy_getinfo</code></a> in libcurl, where
-<em>option</em> is the same as the CURLINFO_* constants in libcurl,
-except that the CURLINFO_ prefix has been removed.
-(See below for exceptions.)
-<em>Result</em> contains an integer, float or string, depending on
-which option is given. The <code>getinfo</code> method should
-not be called unless <code>perform</code> has been called and
-finished.</p>
-
-<p>Example usage:</p>
-
-<pre>
-import pycurl
-c = pycurl.Curl()
-c.setopt(pycurl.URL, "http://sf.net")
-c.setopt(pycurl.FOLLOWLOCATION, 1)
-c.perform()
-print c.getinfo(pycurl.HTTP_CODE), c.getinfo(pycurl.EFFECTIVE_URL)
-...
---&gt; 200 "http://sourceforge.net/"
-</pre>
-</dd>
-
-<dt><code>pause(</code><em>bitmask</em><code>) </code>-&gt; <em>None</em></dt>
-<dd>
-<p>Corresponds to
-<a href="http://curl.haxx.se/libcurl/c/curl_easy_pause.html"><code>curl_easy_pause</code></a>
-in libcurl. The argument should be derived from
-the <code>PAUSE_RECV</code>, <code>PAUSE_SEND</code>, <code>PAUSE_ALL</code>
-and <code>PAUSE_CONT</code> constants.</p>
-
-<dt><code>errstr()</code> -&gt; <em>String</em></dt>
-<dd>
-<p>Returns the internal libcurl error buffer of this handle as a string.</p>
-</dd>
-</dl>
-
-<p>In order to distinguish between similarly-named CURLOPT and
-CURLINFO constants, some have <code>OPT_</code>
-and <code>INFO_</code> prefixes. These are
-<code>INFO_FILETIME</code>, <code>OPT_FILETIME</code>,
-<code>INFO_COOKIELIST</code> (but <code>setopt</code> uses <code>COOKIELIST</code>!),
-<code>INFO_CERTINFO</code>, and <code>OPT_CERTINFO</code>.</p>
-
-<p>The value returned by <code>getinfo(INFO_CERTINFO)</code> is a list
-with one element per certificate in the chain, starting with the leaf;
-each element is a sequence
-of <code>(</code><em>key</em><code>, </code><em>value</em><code>)</code>
-tuples.</p>
-
-<hr />
-<p>
-  <a href="http://validator.w3.org/check/referer"><img align="right"
-     src="http://www.w3.org/Icons/valid-xhtml10"
-     alt="Valid XHTML 1.0!" height="31" width="88" border="0" /></a>
-</p>
-
-</body>
-</html>
diff --git a/doc/curlobject.rst b/doc/curlobject.rst
new file mode 100644
index 0000000..3720766
--- /dev/null
+++ b/doc/curlobject.rst
@@ -0,0 +1,95 @@
+Curl Object
+===========
+
+Curl objects have the following methods:
+
+**close**\ () -> *None*
+
+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.
+
+**reset**\ () -> *None*
+
+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_``
+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.
+
+Example usage:
+
+::
+
+    import pycurl
+    c = pycurl.Curl()
+    c.setopt(pycurl.URL, "http://www.python.org/")
+    c.setopt(pycurl.HTTPHEADER, ["Accept:"])
+    import StringIO
+    b = StringIO.StringIO()
+    c.setopt(pycurl.WRITEFUNCTION, b.write)
+    c.setopt(pycurl.FOLLOWLOCATION, 1)
+    c.setopt(pycurl.MAXREDIRS, 5)
+    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
+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.
+
+Example usage:
+
+::
+
+    import pycurl
+    c = pycurl.Curl()
+    c.setopt(pycurl.URL, "http://sf.net")
+    c.setopt(pycurl.FOLLOWLOCATION, 1)
+    c.perform()
+    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
+derived from the ``PAUSE_RECV``, ``PAUSE_SEND``, ``PAUSE_ALL`` and
+``PAUSE_CONT`` constants.
+
+**errstr**\ () -> *String*
+
+Returns the internal libcurl error buffer of this handle as a string.
+
+In order to distinguish between similarly-named CURLOPT and CURLINFO
+constants, some have ``OPT_`` and ``INFO_`` prefixes. These are
+``INFO_FILETIME``, ``OPT_FILETIME``, ``INFO_COOKIELIST`` (but ``setopt`` uses
+``COOKIELIST``!), ``INFO_CERTINFO``, and ``OPT_CERTINFO``.
+
+The value returned by ``getinfo(INFO_CERTINFO)`` is a list with one element
+per certificate in the chain, starting with the leaf; each element is a
+sequence of ``(``*key*``, ``*value*``)`` tuples.
+
+.. _curl_easy_cleanup:
+    http://curl.haxx.se/libcurl/c/curl_easy_cleanup.html
+.. _curl_easy_perform:
+    http://curl.haxx.se/libcurl/c/curl_easy_perform.html
+.. _curl_easy_reset: http://curl.haxx.se/libcurl/c/curl_easy_reset.html
+.. _curl_easy_setopt: http://curl.haxx.se/libcurl/c/curl_easy_setopt.html
+.. _curl_easy_getinfo:
+    http://curl.haxx.se/libcurl/c/curl_easy_getinfo.html
+.. _curl_easy_pause: http://curl.haxx.se/libcurl/c/curl_easy_pause.html
diff --git a/doc/curlshareobject.html b/doc/curlshareobject.html
deleted file mode 100644
index a624f48..0000000
--- a/doc/curlshareobject.html
+++ /dev/null
@@ -1,53 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
-    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
-  <title>PycURL: CurlShare Objects</title>
-  <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
-  <meta name="revisit-after" content="30 days" />
-  <meta name="robots" content="noarchive, index, follow" />
-</head>
-<body>
-
-<h1>CurlShare Object</h1>
-
-<p>CurlShare objects have the following methods:</p>
-
-<dl>
-<dt><code>setopt(</code><em>option, value</em><code>)</code> -&gt; <em>None</em></dt>
-<dd>
-
-<p>Corresponds to
-<a
-href="http://curl.haxx.se/libcurl/c/curl_share_setopt.html"><code>curl_share_setopt</code></a> in libcurl, where
-<em>option</em> is specified with the CURLSHOPT_* constants in libcurl,
-except that the CURLSHOPT_ prefix has been changed to SH_.  Currently,
-<em>value</em> must be either LOCK_DATA_COOKIE or LOCK_DATA_DNS.</p>
-
-<p>Example usage:</p>
-
-<pre>
-import pycurl
-curl = pycurl.Curl()
-s = pycurl.CurlShare()
-s.setopt(pycurl.SH_SHARE, pycurl.LOCK_DATA_COOKIE)
-s.setopt(pycurl.SH_SHARE, pycurl.LOCK_DATA_DNS)
-curl.setopt(pycurl.URL, 'http://curl.haxx.se')
-curl.setopt(pycurl.SHARE, s)
-curl.perform()
-curl.close()
-</pre>
-</dd>
-
-</dl>
-
-<hr />
-<p>
-  <a href="http://validator.w3.org/check/referer"><img align="right"
-     src="http://www.w3.org/Icons/valid-xhtml10"
-     alt="Valid XHTML 1.0!" height="31" width="88" border="0" /></a>
-</p>
-
-</body>
-</html>
diff --git a/doc/curlshareobject.rst b/doc/curlshareobject.rst
new file mode 100644
index 0000000..cf1d17b
--- /dev/null
+++ b/doc/curlshareobject.rst
@@ -0,0 +1,29 @@
+CurlShare Object
+================
+
+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``.
+
+Example usage:
+
+::
+
+    import pycurl
+    curl = pycurl.Curl()
+    s = pycurl.CurlShare()
+    s.setopt(pycurl.SH_SHARE, pycurl.LOCK_DATA_COOKIE)
+    s.setopt(pycurl.SH_SHARE, pycurl.LOCK_DATA_DNS)
+    curl.setopt(pycurl.URL, 'http://curl.haxx.se')
+    curl.setopt(pycurl.SHARE, s)
+    curl.perform()
+    curl.close()
+
+
+.. _curl_share_setopt:
+    http://curl.haxx.se/libcurl/c/curl_share_setopt.html
diff --git a/doc/pycurl.html b/doc/pycurl.html
deleted file mode 100644
index bde7753..0000000
--- a/doc/pycurl.html
+++ /dev/null
@@ -1,138 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
-    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
-  <title>PycURL Documentation</title>
-  <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
-  <meta name="revisit-after" content="30 days" />
-  <meta name="robots" content="noarchive, index, follow" />
-</head>
-<body>
-
-<h1><tt>PycURL</tt> &mdash; A Python Interface To The cURL library</h1>
-
-<p>The pycurl package is a Python interface to libcurl (<a
-href="http://curl.haxx.se/libcurl/">http://curl.haxx.se/libcurl/</a>). pycurl
-has been successfully built and tested with Python versions from
-2.4 to 2.7.</p>
-
-<p>libcurl is a client-side URL transfer library supporting FTP, FTPS,
-HTTP, HTTPS, GOPHER, TELNET, DICT, FILE and LDAP.  libcurl
-also supports HTTPS certificates, HTTP POST, HTTP PUT, FTP uploads, proxies,
-cookies, basic authentication, file transfer resume of FTP sessions, HTTP
-proxy tunneling and more.</p>
-
-<p>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
-(<a href="http://curl.haxx.se/libcurl/c/">http://curl.haxx.se/libcurl/c/</a>).</p>
-
-<hr/>
-
-<h1>Module Functionality</h1>
-
-<dl>
-<dt><code>pycurl.global_init(</code><em>option</em><code>)</code> -&gt;<em>None</em></dt>
-
-<dd><p><em>option</em> is one of the constants
-pycurl.GLOBAL_SSL, pycurl.GLOBAL_WIN32, pycurl.GLOBAL_ALL,
-pycurl.GLOBAL_NOTHING, pycurl.GLOBAL_DEFAULT.  Corresponds to
-<a href="http://curl.haxx.se/libcurl/c/curl_global_init.html"><code>curl_global_init()</code></a> in libcurl.</p>
-</dd>
-
-<dt><code>pycurl.global_cleanup()</code> -&gt; <em>None</em></dt>
-<dd>
-<p>Corresponds to
-<a href="http://curl.haxx.se/libcurl/c/curl_global_cleanup.html"><code>curl_global_cleanup()</code></a> in libcurl.</p>
-</dd>
-
-<dt><code>pycurl.version</code></dt>
-
-<dd><p>This is a string with version information on libcurl,
-corresponding to
-<a href="http://curl.haxx.se/libcurl/c/curl_version.html"><code>curl_version()</code></a> in libcurl.</p>
-
-<p>Example usage:</p>
-<pre>
->>> import pycurl
->>> pycurl.version
-'libcurl/7.12.3 OpenSSL/0.9.7e zlib/1.2.2.1 libidn/0.5.12'
-</pre>
-</dd>
-
-<dt><code>pycurl.version_info()</code> -&gt; <em>Tuple</em></dt>
-<dd>
-<p>Corresponds to
-<a href="http://curl.haxx.se/libcurl/c/curl_version_info.html"><code>curl_version_info()</code></a> in libcurl.
-Returns a tuple of information which is similar to the
-<code>curl_version_info_data</code> struct returned by
-<code>curl_version_info()</code> in libcurl.</p>
-
-<p>Example usage:</p>
-<pre>
->>> 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')
-</pre>
-</dd>
-
-<dt><code>pycurl.Curl()</code> -&gt; <em>Curl object</em></dt>
-<dd>
-<p>This function creates a new
-<a href="curlobject.html">Curl object</a> which corresponds to a
-<code>CURL</code> handle in libcurl. Curl objects automatically
-set CURLOPT_VERBOSE to 0, CURLOPT_NOPROGRESS to 1,
-provide a default CURLOPT_USERAGENT and setup
-CURLOPT_ERRORBUFFER to point to a private error buffer.</p>
-</dd>
-
-<dt><code>pycurl.CurlMulti()</code> -&gt; <em>CurlMulti object</em></dt>
-<dd>
-<p>This function creates a new
-<a href="curlmultiobject.html">CurlMulti object</a> which corresponds to
-a <code>CURLM</code> handle in libcurl.</p>
-</dd>
-
-<dt><code>pycurl.CurlShare()</code> -&gt; <em>CurlShare object</em></dt>
-<dd>
-<p>This function creates a new
-<a href="curlshareobject.html">CurlShare object</a> which corresponds to
-a <code>CURLSH</code> handle in libcurl.  CurlShare objects is what you
-pass as an argument to the SHARE option on Curl objects.</p>
-</dd>
-
-</dl>
-
-<hr/>
-
-<h1>Subsections</h1>
-
-<ul>
-  <li><a href="curlobject.html">Curl objects</a></li>
-  <li><a href="curlmultiobject.html">CurlMulti objects</a></li>
-  <li><a href="curlshareobject.html">CurlShare objects</a></li>
-  <li><a href="callbacks.html">Callbacks</a></li>
-  <li><a href="unicode.html">Unicode handling</a></li>
-  <li><a href="files.html">File handling</a></li>
-</ul>
-
-<h1>Documentation For Developers</h1>
-
-<ul>
-  <li><a href="internals.html">Notes on PycURL internals</a></li>
-  <li><a href="release-process.html">Release process</a></li>
-</ul>
-
-<hr />
-<p>
-  <a href="http://validator.w3.org/check/referer"><img align="right"
-     src="http://www.w3.org/Icons/valid-xhtml10"
-     alt="Valid XHTML 1.0!" height="31" width="88" border="0" /></a>
-</p>
-
-</body>
-</html>
diff --git a/doc/pycurl.rst b/doc/pycurl.rst
new file mode 100644
index 0000000..60971df
--- /dev/null
+++ b/doc/pycurl.rst
@@ -0,0 +1,114 @@
+``PycURL`` -- A Python Interface To The cURL library
+====================================================
+
+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
+certificates, HTTP POST, HTTP PUT, FTP uploads, proxies, cookies, basic
+authentication, file transfer resume of FTP sessions, HTTP proxy tunneling
+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 C API`_.
+
+Module Functionality
+--------------------
+
+**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.
+
+**pycurl.global_cleanup**\ () -> *None*
+
+Corresponds to `curl_global_cleanup`_ in libcurl.
+
+**pycurl.version**
+
+This is a string with version information on libcurl, corresponding to
+`curl_version`_ in libcurl.
+
+Example usage:
+
+::
+
+    >>> import pycurl
+    >>> pycurl.version
+    '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
+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()
+    (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,
+CURLOPT_NOPROGRESS to 1, provide a default CURLOPT_USERAGENT and setup
+CURLOPT_ERRORBUFFER to point to a private error buffer.
+
+**pycurl.CurlMulti**\ () -> *CurlMulti object*
+
+This function creates a new `CurlMulti object`_ which corresponds to a
+``CURLM`` handle in libcurl.
+
+**pycurl.CurlShare**\ () -> *CurlShare object*
+
+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.
+
+
+Subsections
+-----------
+
+-   `Curl objects`_
+-   `CurlMulti objects`_
+-   `CurlShare objects`_
+-   `Callbacks`_
+-   `Unicode handling`_
+-   `File handling`_
+
+
+Documentation For Developers
+============================
+
+-   `Notes on PycURL internals`_
+-   `Release process`_
+
+.. _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
+.. _CurlMulti objects: curlmultiobject.html
+.. _CurlShare object: curlshareobject.html
+.. _CurlShare objects: curlshareobject.html
+.. _Callbacks: callbacks.html
+.. _Unicode handling: unicode.html
+.. _File handling: files.html
+.. _Notes on PycURL internals: internals.html
+.. _Release process: release-process.html
diff --git a/setup.py b/setup.py
index 3b20172..3be87c8 100644
--- a/setup.py
+++ b/setup.py
@@ -383,9 +383,9 @@ def get_data_files():
     files = ["ChangeLog", "COPYING-LGPL", "COPYING-MIT", "INSTALL", "README.rst"]
     if files:
         data_files.append((os.path.join(datadir), files))
-    files = glob.glob(os.path.join("doc", "*.html"))
+    files = glob.glob(os.path.join("doc", "*.rst"))
     if files:
-        data_files.append((os.path.join(datadir, "html"), files))
+        data_files.append((os.path.join(datadir, "rst"), files))
     files = glob.glob(os.path.join("examples", "*.py"))
     if files:
         data_files.append((os.path.join(datadir, "examples"), files))
author	Oleg Pudeyev <oleg@bsdpower.com>	2014-01-16 20:41:22 -0800
committer	Oleg Pudeyev <oleg@bsdpower.com>	2014-01-16 20:41:22 -0800
commit	5576e7909deb123856da3debc6caf6314c4a771a (patch)
tree	f9e834eeb3a7b2901bc24584963fb2d33d10eda1
parent	f3d35fb0a5494c7e1d4c9ac49157bd3360773a94 (diff)
parent	77757d8427979aac1600ef699bb6d4e6db4a2107 (diff)
download	pycurl-5576e7909deb123856da3debc6caf6314c4a771a.tar.gz