docs(api): add separate section for advanced usage

3 files changed, 164 insertions, 160 deletions

diff --git a/docs/api-usage-advanced.rst b/docs/api-usage-advanced.rst
new file mode 100644
index 0000000..53a3977
--- /dev/null
+++ b/docs/api-usage-advanced.rst
@@ -0,0 +1,163 @@
+##############
+Advanced usage
+##############
+
+Using a custom session
+----------------------
+
+python-gitlab relies on ``requests.Session`` objects to perform all the
+HTTP requests to the Gitlab servers.
+
+You can provide your own ``Session`` object with custom configuration when
+you create a ``Gitlab`` object.
+
+Context manager
+---------------
+
+You can use ``Gitlab`` objects as context managers. This makes sure that the
+``requests.Session`` object associated with a ``Gitlab`` instance is always
+properly closed when you exit a ``with`` block:
+
+.. code-block:: python
+
+   with gitlab.Gitlab(host, token) as gl:
+       gl.projects.list()
+
+.. warning::
+
+   The context manager will also close the custom ``Session`` object you might
+   have used to build the ``Gitlab`` instance.
+
+Proxy configuration
+-------------------
+
+The following sample illustrates how to define a proxy configuration when using
+python-gitlab:
+
+.. code-block:: python
+
+   import os
+   import gitlab
+   import requests
+
+   session = requests.Session()
+   session.proxies = {
+       'https': os.environ.get('https_proxy'),
+       'http': os.environ.get('http_proxy'),
+   }
+   gl = gitlab.gitlab(url, token, api_version=4, session=session)
+
+Reference:
+https://requests.readthedocs.io/en/latest/user/advanced/#proxies
+
+SSL certificate verification
+----------------------------
+
+python-gitlab relies on the CA certificate bundle in the `certifi` package
+that comes with the requests library.
+
+If you need python-gitlab to use your system CA store instead, you can provide
+the path to the CA bundle in the `REQUESTS_CA_BUNDLE` environment variable.
+
+Reference:
+https://requests.readthedocs.io/en/latest/user/advanced/#ssl-cert-verification
+
+Client side certificate
+-----------------------
+
+The following sample illustrates how to use a client-side certificate:
+
+.. code-block:: python
+
+   import gitlab
+   import requests
+
+   session = requests.Session()
+   session.cert = ('/path/to/client.cert', '/path/to/client.key')
+   gl = gitlab.gitlab(url, token, api_version=4, session=session)
+
+Reference:
+https://requests.readthedocs.io/en/latest/user/advanced/#client-side-certificates
+
+Rate limits
+-----------
+
+python-gitlab obeys the rate limit of the GitLab server by default.  On
+receiving a 429 response (Too Many Requests), python-gitlab sleeps for the
+amount of time in the Retry-After header that GitLab sends back.  If GitLab
+does not return a response with the Retry-After header, python-gitlab will
+perform an exponential backoff.
+
+If you don't want to wait, you can disable the rate-limiting feature, by
+supplying the ``obey_rate_limit`` argument.
+
+.. code-block:: python
+
+   import gitlab
+   import requests
+
+   gl = gitlab.gitlab(url, token, api_version=4)
+   gl.projects.list(all=True, obey_rate_limit=False)
+
+If you do not disable the rate-limiting feature, you can supply a custom value
+for ``max_retries``; by default, this is set to 10. To retry without bound when
+throttled, you can set this parameter to -1. This parameter is ignored if
+``obey_rate_limit`` is set to ``False``.
+
+.. code-block:: python
+
+   import gitlab
+   import requests
+
+   gl = gitlab.gitlab(url, token, api_version=4)
+   gl.projects.list(all=True, max_retries=12)
+
+.. warning::
+
+   You will get an Exception, if you then go over the rate limit of your GitLab instance.
+
+Transient errors
+----------------
+
+GitLab server can sometimes return a transient HTTP error.
+python-gitlab can automatically retry in such case, when
+``retry_transient_errors`` argument is set to ``True``.  When enabled,
+HTTP error codes 500 (Internal Server Error), 502 (502 Bad Gateway),
+503 (Service Unavailable), and 504 (Gateway Timeout) are retried. It will retry until reaching
+the `max_retries` value. By default, `retry_transient_errors` is set to `False` and an exception
+is raised for these errors.
+
+.. code-block:: python
+
+   import gitlab
+   import requests
+
+   gl = gitlab.gitlab(url, token, api_version=4)
+   gl.projects.list(all=True, retry_transient_errors=True)
+
+The default ``retry_transient_errors`` can also be set on the ``Gitlab`` object
+and overridden by individual API calls.
+
+.. code-block:: python
+
+   import gitlab
+   import requests
+   gl = gitlab.gitlab(url, token, api_version=4, retry_transient_errors=True)
+   gl.projects.list(all=True)                               # retries due to default value
+   gl.projects.list(all=True, retry_transient_errors=False) # does not retry
+
+Timeout
+-------
+
+python-gitlab will by default use the ``timeout`` option from its configuration
+for all requests. This is passed downwards to the ``requests`` module at the
+time of making the HTTP request. However if you would like to override the
+global timeout parameter for a particular call, you can provide the ``timeout``
+parameter to that API invocation:
+
+.. code-block:: python
+
+   import gitlab
+
+   gl = gitlab.gitlab(url, token, api_version=4)
+   gl.projects.import_github(ACCESS_TOKEN, 123456, "root", timeout=120.0)
diff --git a/docs/api-usage.rst b/docs/api-usage.rst
index d74814f..4b51f48 100644
--- a/docs/api-usage.rst
+++ b/docs/api-usage.rst
@@ -345,166 +345,6 @@ user. For example:
 
    p = gl.projects.create({'name': 'awesome_project'}, sudo='user1')
 
-Advanced HTTP configuration
-===========================
-
-python-gitlab relies on ``requests`` ``Session`` objects to perform all the
-HTTP requests to the Gitlab servers.
-
-You can provide your own ``Session`` object with custom configuration when
-you create a ``Gitlab`` object.
-
-Context manager
----------------
-
-You can use ``Gitlab`` objects as context managers. This makes sure that the
-``requests.Session`` object associated with a ``Gitlab`` instance is always
-properly closed when you exit a ``with`` block:
-
-.. code-block:: python
-
-   with gitlab.Gitlab(host, token) as gl:
-       gl.projects.list()
-
-.. warning::
-
-   The context manager will also close the custom ``Session`` object you might
-   have used to build the ``Gitlab`` instance.
-
-Proxy configuration
--------------------
-
-The following sample illustrates how to define a proxy configuration when using
-python-gitlab:
-
-.. code-block:: python
-
-   import os
-   import gitlab
-   import requests
-
-   session = requests.Session()
-   session.proxies = {
-       'https': os.environ.get('https_proxy'),
-       'http': os.environ.get('http_proxy'),
-   }
-   gl = gitlab.gitlab(url, token, api_version=4, session=session)
-
-Reference:
-https://requests.readthedocs.io/en/latest/user/advanced/#proxies
-
-SSL certificate verification
-----------------------------
-
-python-gitlab relies on the CA certificate bundle in the `certifi` package
-that comes with the requests library.
-
-If you need python-gitlab to use your system CA store instead, you can provide
-the path to the CA bundle in the `REQUESTS_CA_BUNDLE` environment variable.
-
-Reference:
-https://requests.readthedocs.io/en/latest/user/advanced/#ssl-cert-verification
-
-Client side certificate
------------------------
-
-The following sample illustrates how to use a client-side certificate:
-
-.. code-block:: python
-
-   import gitlab
-   import requests
-
-   session = requests.Session()
-   session.cert = ('/path/to/client.cert', '/path/to/client.key')
-   gl = gitlab.gitlab(url, token, api_version=4, session=session)
-
-Reference:
-https://requests.readthedocs.io/en/latest/user/advanced/#client-side-certificates
-
-Rate limits
------------
-
-python-gitlab obeys the rate limit of the GitLab server by default.  On
-receiving a 429 response (Too Many Requests), python-gitlab sleeps for the
-amount of time in the Retry-After header that GitLab sends back.  If GitLab
-does not return a response with the Retry-After header, python-gitlab will
-perform an exponential backoff.
-
-If you don't want to wait, you can disable the rate-limiting feature, by
-supplying the ``obey_rate_limit`` argument.
-
-.. code-block:: python
-
-   import gitlab
-   import requests
-
-   gl = gitlab.gitlab(url, token, api_version=4)
-   gl.projects.list(all=True, obey_rate_limit=False)
-
-If you do not disable the rate-limiting feature, you can supply a custom value
-for ``max_retries``; by default, this is set to 10. To retry without bound when
-throttled, you can set this parameter to -1. This parameter is ignored if
-``obey_rate_limit`` is set to ``False``.
-
-.. code-block:: python
-
-   import gitlab
-   import requests
-
-   gl = gitlab.gitlab(url, token, api_version=4)
-   gl.projects.list(all=True, max_retries=12)
-
-.. warning::
-
-   You will get an Exception, if you then go over the rate limit of your GitLab instance.
-
-Transient errors
-----------------
-
-GitLab server can sometimes return a transient HTTP error.
-python-gitlab can automatically retry in such case, when
-``retry_transient_errors`` argument is set to ``True``.  When enabled,
-HTTP error codes 500 (Internal Server Error), 502 (502 Bad Gateway),
-503 (Service Unavailable), and 504 (Gateway Timeout) are retried. It will retry until reaching
-the `max_retries` value. By default, `retry_transient_errors` is set to `False` and an exception
-is raised for these errors.
-
-.. code-block:: python
-
-   import gitlab
-   import requests
-
-   gl = gitlab.gitlab(url, token, api_version=4)
-   gl.projects.list(all=True, retry_transient_errors=True)
-
-The default ``retry_transient_errors`` can also be set on the ``Gitlab`` object
-and overridden by individual API calls.
-
-.. code-block:: python
-
-   import gitlab
-   import requests
-   gl = gitlab.gitlab(url, token, api_version=4, retry_transient_errors=True)
-   gl.projects.list(all=True)                               # retries due to default value
-   gl.projects.list(all=True, retry_transient_errors=False) # does not retry
-
-Timeout
--------
-
-python-gitlab will by default use the ``timeout`` option from it's configuration
-for all requests. This is passed downwards to the ``requests`` module at the
-time of making the HTTP request. However if you would like to override the
-global timeout parameter for a particular call, you can provide the ``timeout``
-parameter to that API invocation:
-
-.. code-block:: python
-
-   import gitlab
-
-   gl = gitlab.gitlab(url, token, api_version=4)
-   gl.projects.import_github(ACCESS_TOKEN, 123456, "root", timeout=120.0)
-
 .. _object_attributes:
 
 Attributes in updated objects
diff --git a/docs/index.rst b/docs/index.rst
index 22b926d..86ae17c 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -6,6 +6,7 @@
 
    cli-usage
    api-usage
+   api-usage-advanced
    cli-examples
    api-objects
    api/gitlab