docs: Explain how to configure the Python bindings.

The Python bindings (which are used for bots, amongst other things) can
be configured either with a .zuliprc file or with environment variables
in the host machine.

This new page in the user docs explains how to set the bindings up using
both techniques, and is a good reference on the setup required by Zulip
bots.

templates/zerver/api/api-keys.md

@@ -22,34 +22,7 @@ your bot's details:
 
 <img class="screenshot" src="/static/images/api/download-zuliprc.png" />
 
-Or you may also create it manually, as follows:
+Another alternative is manually creating your own `.zuliprc` file, or setting
-
+environment variables that are equivalent. You can find out more about these
-```
+methods [here](/api/configuring-python-bindings).
-[api]
-key=BOT_API_KEY
-email=BOT_EMAIL_ADDRESS
-```
-
-Additionally, you can also specify the parameters as environment variables as follows:
-
-```
-export ZULIP_CONFIG=/path/to/zulipconfig
-export ZULIP_EMAIL=BOT_EMAIL_ADDRESS
-export ZULIP_API_KEY=BOT_API_KEY
-```
-
-The parameters specified in environment variables would override the parameters
-provided in the config file. For example, if you specify the variable `key`
-in the config file and specify `ZULIP_API_KEY` as an environment variable,
-the value of `ZULIP_API_KEY` would be considered.
-
-The following variables can be specified:
-
-1. `ZULIP_CONFIG`
-2. `ZULIP_API_KEY`
-3. `ZULIP_EMAIL`
-4. `ZULIP_SITE`
-5. `ZULIP_CERT`
-6. `ZULIP_CERT_KEY`
-7. `ZULIP_CERT_BUNDLE`
 

templates/zerver/api/configuring-python-bindings.md

@@ -0,0 +1,104 @@
+# Configuring the Python bindings
+
+Zulip provides a set of tools that allows interacting with its API more
+easily, called the [Python bindings](https://pypi.python.org/pypi/zulip/).
+One of the most notable use cases for these bindings are bots developed
+using Zulip's [bot framework](/#writing-bots).
+
+In order to use them, you need to configure them with your API key and other
+settings. There are two ways to achieve that:
+
+ - With a file called `.zuliprc`, located in your home directory.
+ - With [environment variables](https://en.wikipedia.org/wiki/
+Environment_variable) set up in your host machine.
+
+A `.zuliprc` file is a plain text document that has the same format as
+Microsft Windows INI files. It looks like this:
+
+```
+[api]
+key=<api key from the web interface>
+email=<your email address>
+site=<your Zulip server's URI>
+...
+```
+
+The keys you can use in this file (and their equivalent environment variables)
+can be found in the following table:
+
+<table class="table">
+    <thead>
+        <tr>
+            <th><code>.zuliprc</code> key</th>
+            <th>Environment variable</th>
+            <th>Required</th>
+            <th>Description</th>
+        </tr>
+    </thead>
+    <tr>
+        <td><code>key</code></td>
+        <td><code>ZULIP_API_KEY</code></td>
+        <td>Yes</td>
+        <td>
+            <a href="/api/api-keys">API key</a>, which you can get through
+            Zulip's web interface.</a>
+        </td>
+    </tr>
+    <tr>
+        <td><code>email</code></td>
+        <td><code>ZULIP_EMAIL</code></td>
+        <td>Yes</td>
+        <td>
+            The email address of the user who owns the API key mentioned
+            above.
+        </td>
+    </tr>
+    <tr>
+        <td><code>site</code></td>
+        <td><code>ZULIP_SITE</code></td>
+        <td>No</td>
+        <td>
+            URL where your Zulip server is located.
+        </td>
+    </tr>
+    <tr>
+        <td><code>client_cert_key</code></td>
+        <td><code>ZULIP_CERT_KEY</code></td>
+        <td>No</td>
+        <td>
+            Path to the SSL/TLS private key that the binding should use to
+            connect to the server.
+        </td>
+    </tr>
+    <tr>
+        <td><code>client_cert</code></td>
+        <td><code>ZULIP_CERT</code></td>
+        <td>No*</td>
+        <td>
+            The public counterpart of <code>client_cert_key</code>/
+            <code>ZULIP_CERT_KEY</code>. <i>This setting is required if a cert
+            key has been set.</i>
+        </td>
+    </tr>
+    <tr>
+        <td><code>client_bundle</code></td>
+        <td><code>ZULIP_CERT_BUNDLE</code></td>
+        <td>No</td>
+        <td>
+            Path where the server's PEM-encoded certificate is located. CA
+            certificates are also accepted, in case those CA's have issued the
+            server's certificate. Defaults to the built-in CA bundle trusted
+            by Python.
+        </td>
+    </tr>
+    <tr>
+        <td><code>insecure</code></td>
+        <td><code>ZULIP_ALLOW_INSECURE</code></td>
+        <td>No</td>
+        <td>
+            Allows connecting to Zulip servers with an invalid SSL/TLS
+            certificate. Please note that enabling this will make the HTTPS
+            connection insecure. Defaults to <code>false</code>.
+        </td>
+    </tr>
+</table>

templates/zerver/api/sidebar.md

@@ -19,6 +19,7 @@
 * [Overview](/api/rest)
 * [Installation instructions](/api/installation-instructions)
 * [API keys](/api/api-keys)
+* [Configuring the Python bindings](/api/configuring-python-bindings)
 * [Error handling](/api/rest-error-handling)
 
 {!rest_endpoints.md!}