docs: Extract advanced usage, add proxy info

ihabunek · Dec 30, 2018 · 7195a05 · 7195a05
1 parent 226713a
commit 7195a05
Show file tree

Hide file tree

Showing 4 changed files with 51 additions and 19 deletions.
diff --git a/docs/_static/auth.png b/docs/_static/auth.png
diff --git a/docs/advanced.rst b/docs/advanced.rst
@@ -0,0 +1,40 @@
+==============
+Advanced usage
+==============
+
+Disabling HTTPS
+---------------
+
+You may pass the ``--disable-https`` flag to use unencrypted HTTP instead of
+HTTPS for a given instance. This is inherently insecure and should be used only
+when connecting to local development instances.
+
+.. code-block:: sh
+
+    toot login --disable-https --instance localhost:8080
+
+Using proxies
+-------------
+
+You can configure proxies by setting the ``HTTPS_PROXY`` or ``HTTP_PROXY``
+environment variables. This will cause all http(s) requests to be proxied
+through the specified server.
+
+For example:
+
+.. code-block:: sh
+
+    export HTTPS_PROXY="http://1.2.3.4:5678"
+    toot login --instance mastodon.social
+
+**NB:** This feature is provided by
+`requests <http://docs.python-requests.org/en/master/user/advanced/#proxies>`_
+and setting the environment variable will affect other programs using this
+library.
+
+This environment can be set for a single call to toot by prefixing the command
+with the environment variable:
+
+.. code-block:: sh
+
+    HTTPS_PROXY="http://1.2.3.4:5678" toot login --instance mastodon.social
diff --git a/docs/index.rst b/docs/index.rst
@@ -14,25 +14,26 @@ toot is a commandline tool for interacting with Mastodon social networks.
 .. image:: https://img.shields.io/pypi/v/toot.svg?maxAge=3600&style=flat-square
    :target: https://pypi.python.org/pypi/toot
 
+Features
+--------
+
+* Posting, replying, deleting statuses
+* Support for media uploads, spoiler text, sensitive content
+* Search by account or hash tag
+* Following, muting and blocking accounts
+* Simple switching between multiple Mastodon accounts
+
 Contents
 --------
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    install
    usage
+   advanced
    release
 
-Features
---------
-
-* Posting, replying, deleting statuses
-* Support for media uploads, spoiler text, sensitive content
-* Search by account or hash tag
-* Following, muting and blocking accounts
-* Simple swithcing between authenticated in Mastodon accounts
-
 Curses UI
 ---------
 

diff --git a/docs/usage.rst b/docs/usage.rst
@@ -58,15 +58,6 @@ You will be redirected to your Mastodon instance to log in and authorize toot to
 
 The application and user access tokens will be saved in the configuration file located at ``~/.config/toot/instances/config.json``.
 
-Disabling HTTPS
-~~~~~~~~~~~~~~~
-
-You may pass the ``--disable-https`` flag to use unencrypted HTTP instead of HTTPS for a given instance. This is inherently insecure and should be used only when connecting to local development instances.
-
-.. code-block:: sh
-
-    toot login --disable-https --instance localhost:8080
-
 Using multiple accounts
 ~~~~~~~~~~~~~~~~~~~~~~~