docs(readme): add a basic feature list

nejch · JohnVillalovos · commit b4d53f1abb26 · 2022-10-16T11:08:14.000-07:00
diff --git a/README.rst b/README.rst
@@ -29,13 +29,24 @@ python-gitlab
 
 It supports the v4 API of GitLab, and provides a CLI tool (``gitlab``).
 
-The client aims to let you write clean Python code when managing GitLab resources.
-You can pass arbitrary parameters to the GitLab API - so you only need to
-follow GitLab's current documentation on what parameters are available.
+.. _features:
 
-It also provides lower-level API methods giving you a degree of control and
-usability for any endpoint the moment it is available on GitLab.com or your
-GitLab instance.
+Features
+--------
+
+``python-gitlab`` enables you to:
+
+* write Pythonic code to manage your GitLab resources.
+* pass arbitrary parameters to the GitLab API. Simply follow GitLab's docs
+  on what parameters are available.
+* access arbitrary endpoints as soon as they are available on GitLab, by using
+  lower-level API methods.
+* use persistent requests sessions for authentication, proxy and certificate handling.
+* handle smart retries on network and server errors, with rate-limit handling.
+* flexible handling of paginated responses, including lazy iterators.
+* automatically URL-encode paths and parameters where needed.
+* automatically convert some complex data structures to API attribute types
+* merge configuration from config files, environment variables and arguments.
 
 Installation
 ------------
@@ -63,7 +74,6 @@ From GitLab:
 
    $ pip install git+https://gitlab.com/python-gitlab/python-gitlab.git
 
-
 Using the docker images
 -----------------------
 
diff --git a/docs/api-levels.rst b/docs/api-levels.rst
@@ -22,6 +22,9 @@ Lower-level API - HTTP methods
    At this point, python-gitlab will no longer take care of URL-encoding and other transformations
    needed to correctly pass API parameter types. You have to construct these correctly yourself.
 
+   However, you still benefit from many of the client's :ref:`features` such as authentication,
+   requests and retry handling.
+
 .. important::
 
    If you've found yourself at this section because of an endpoint not yet implemented in
