Improve the docs to make v4 a first class citizen

Gauvain Pocentek · Gauvain Pocentek · commit 60efc83b5a00 · 2017-09-07T21:31:03.000+02:00
diff --git a/docs/api-usage.rst b/docs/api-usage.rst
@@ -2,15 +2,38 @@
 Getting started with the API
 ############################
 
-The ``gitlab`` package provides 3 base types:
+python-gitlab supports both GitLab v3 and v4 APIs.
+
+v3 being deprecated by GitLab, its support in python-gitlab will be minimal.
+The development team will focus on v4.
+
+v3 is still the default API used by python-gitlab, for compatibility reasons..
+
+
+Base types
+==========
+
+The ``gitlab`` package provides some base types.
 
 * ``gitlab.Gitlab`` is the primary class, handling the HTTP requests. It holds
   the GitLab URL and authentication information.
-* ``gitlab.GitlabObject`` is the base class for all the GitLab objects. These
-  objects provide an abstraction for GitLab resources (projects, groups, and so
-  on).
-* ``gitlab.BaseManager`` is the base class for objects managers, providing the
-  API to manipulate the resources and their attributes.
+
+For v4 the following types are defined:
+
+* ``gitlab.base.RESTObject`` is the base class for all the GitLab v4 objects.
+  These objects provide an abstraction for GitLab resources (projects, groups,
+  and so on).
+* ``gitlab.base.RESTManager`` is the base class for v4 objects managers,
+  providing the API to manipulate the resources and their attributes.
+
+For v3 the following types are defined:
+
+* ``gitlab.base.GitlabObject`` is the base class for all the GitLab v3 objects.
+  These objects provide an abstraction for GitLab resources (projects, groups,
+  and so on).
+* ``gitlab.base.BaseManager`` is the base class for v3 objects managers,
+  providing the API to manipulate the resources and their attributes.
+
 
 ``gitlab.Gitlab`` class
 =======================
@@ -40,7 +63,9 @@ You can also use configuration files to create ``gitlab.Gitlab`` objects:
 See the :ref:`cli_configuration` section for more information about
 configuration files.
 
-**GitLab v4 support**
+
+API version
+===========
 
 ``python-gitlab`` uses the v3 GitLab API by default. Use the ``api_version``
 parameter to switch to v4:
@@ -53,15 +78,17 @@ parameter to switch to v4:
 
 .. warning::
 
-   The v4 support is experimental.
+   The python-gitlab API is not the same for v3 and v4. Make sure to read
+   :ref:`switching_to_v4` before upgrading.
+
+   v4 will become the default in python-gitlab.
 
 Managers
 ========
 
 The ``gitlab.Gitlab`` class provides managers to access the GitLab resources.
 Each manager provides a set of methods to act on the resources. The available
-methods depend on the resource type. Resources are represented as
-``gitlab.GitlabObject``-derived objects.
+methods depend on the resource type.
 
 Examples:
 
@@ -84,17 +111,22 @@ Examples:
 
 The attributes of objects are defined upon object creation, and depend on the
 GitLab API itself. To list the available information associated with an object
-use the python introspection tools:
+use the python introspection tools for v3, or the ``attributes`` attribute for
+v4:
 
 .. code-block:: python
 
    project = gl.projects.get(1)
+
+   # v3
    print(vars(project))
    # or
    print(project.__dict__)
 
-Some ``gitlab.GitlabObject`` classes also provide managers to access related
-GitLab resources:
+   # v4
+   print(project.attributes)
+
+Some objects also provide managers to access related GitLab resources:
 
 .. code-block:: python
 
@@ -105,7 +137,7 @@ GitLab resources:
 Gitlab Objects
 ==============
 
-You can update or delete an object when it exists as a ``GitlabObject`` object:
+You can update or delete a remote object when it exists locally:
 
 .. code-block:: python
 
@@ -119,15 +151,31 @@ You can update or delete an object when it exists as a ``GitlabObject`` object:
    project.delete()
 
 
-Some ``GitlabObject``-derived classes provide additional methods, allowing more
-actions on the GitLab resources. For example:
+Some classes provide additional methods, allowing more actions on the GitLab
+resources. For example:
 
 .. code-block:: python
 
    # star a git repository
    project = gl.projects.get(1)
    project.star()
 
+Lazy objects (v4 only)
+======================
+
+To avoid useless calls to the server API, you can create lazy objects. These
+objects are created locally using a known ID, and give access to other managers
+and methods.
+
+The following exemple will only make one API call to the GitLab server to star
+a project:
+
+.. code-block:: python
+
+   # star a git repository
+   project = gl.projects.get(1, lazy=True)  # no API call
+   project.star()  # API call
+
 Pagination
 ==========
 
@@ -142,16 +190,15 @@ listing methods support the ``page`` and ``per_page`` parameters:
 
    The first page is page 1, not page 0.
 
-
-By default GitLab does not return the complete list of items.  Use the ``all``
+By default GitLab does not return the complete list of items. Use the ``all``
 parameter to get all the items when using listing methods:
 
 .. code-block:: python
 
    all_groups = gl.groups.list(all=True)
    all_owned_projects = gl.projects.owned(all=True)
 
-.. note::
+.. warning::
 
    python-gitlab will iterate over the list by calling the corresponding API
    multiple times. This might take some time if you have a lot of items to
@@ -160,6 +207,15 @@ parameter to get all the items when using listing methods:
    use ``safe_all=True`` instead to stop pagination automatically if the
    recursion limit is hit.
 
+With v4, ``list()`` methods can also return a generator object which will
+handle the next calls to the API when required:
+
+.. code-block:: python
+
+   items = gl.groups.list(as_list=False)
+   for item in items:
+       print(item.attributes)
+
 Sudo
 ====
 
diff --git a/docs/cli.rst b/docs/cli.rst
@@ -28,7 +28,8 @@ Content
 -------
 
 The configuration file uses the ``INI`` format. It contains at least a
-``[global]`` section, and a new section for each GitLab server. For example:
+``[global]`` section, and a specific section for each GitLab server. For
+example:
 
 .. code-block:: ini
 
@@ -98,7 +99,7 @@ CLI
 Objects and actions
 -------------------
 
-The ``gitlab`` command expects two mandatory arguments. This first one is the
+The ``gitlab`` command expects two mandatory arguments. The first one is the
 type of object that you want to manipulate. The second is the action that you
 want to perform. For example:
 
@@ -140,8 +141,8 @@ These options must be defined before the mandatory arguments.
     Output format. Defaults to a custom format. Can also be ``yaml`` or ``json``.
 
 ``--fields``, ``-f``
-    Comma-separated list of fields to display (``yaml`` and ``json`` formats
-    only).  If not used, all the object fields are displayed.
+    Comma-separated list of fields to display (``yaml`` and ``json`` output
+    formats only).  If not used, all the object fields are displayed.
 
 Example:
 
diff --git a/docs/switching-to-v4.rst b/docs/switching-to-v4.rst
@@ -1,3 +1,5 @@
+.. _switching_to_v4:
+
 ##########################
 Switching to GtiLab API v4
 ##########################
@@ -10,15 +12,12 @@ GitLab will stop supporting the v3 API soon, and you should consider switching
 to v4 if you use a recent version of GitLab (>= 9.0), or if you use
 http://gitlab.com.
 
-The new v4 API is available in the `rework_api branch on github
-<https://github.com/python-gitlab/python-gitlab/tree/rework_api>`_, and will be
-released soon.
-
 
 Using the v4 API
 ================
 
-To use the new v4 API, explicitly use it in the ``Gitlab`` constructor:
+To use the new v4 API, explicitly define ``api_version` `in the ``Gitlab``
+constructor:
 
 .. code-block:: python
 
@@ -79,7 +78,7 @@ following important changes in the python API:
   calls.
 
   To limit the number of API calls, you can now use ``get()`` methods with the
-  ``lazy=True`` parameter.  This creates shallow objects that provide usual
+  ``lazy=True`` parameter. This creates shallow objects that provide usual
   managers.
 
   The following v3 code:
