docs: switch to Furo and refresh introduction pages

README.rst

@@ -1,3 +1,6 @@
+python-gitlab
+=============
+
 .. image:: https://github.com/python-gitlab/python-gitlab/workflows/Test/badge.svg
    :target: https://github.com/python-gitlab/python-gitlab/actions
 
@@ -19,32 +22,39 @@
 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
     :target: https://github.com/python/black
 
-Python GitLab
-=============
-
 ``python-gitlab`` is a Python package providing access to the GitLab server API.
 
 It supports the v4 API of GitLab, and provides a CLI tool (``gitlab``).
 
 Installation
-============
-
-Requirements
 ------------
 
-python-gitlab depends on:
+As of 3.0.0, ``python-gitlab`` is compatible with Python 3.7+.
+
+Use ``pip`` to install the latest stable version of ``python-gitlab``:
+
+.. code-block:: console
 
-* `python-requests <https://2.python-requests.org/en/latest/>`_
+   $ pip install --upgrade python-gitlab
 
-Install with pip
-----------------
+The current development version is available on both `GitHub.com
+<https://github.com/python-gitlab/python-gitlab>`__ and `GitLab.com
+<https://gitlab.com/python-gitlab/python-gitlab>`__, and can be
+installed directly from the git repository:
 
 .. code-block:: console
 
-   pip install python-gitlab
+   $ pip install git+https://github.com/python-gitlab/python-gitlab.git
+
+From GitLab:
+
+.. code-block:: console
+
+   $ pip install git+https://gitlab.com/python-gitlab/python-gitlab.git
+
 
 Using the docker image
-======================
+----------------------
 
 You can run the Docker image directly from the GitLab registry:
 
@@ -65,7 +75,7 @@ You can also mount your own config file:
    $ docker run -it --rm -v /path/to/python-gitlab.cfg:/etc/python-gitlab.cfg registry.gitlab.com/python-gitlab/python-gitlab:latest <command> ...
 
 Building the image
-------------------
+~~~~~~~~~~~~~~~~~~
 
 To build your own image from this repository, run:
 
@@ -80,32 +90,32 @@ Run your own image:
    $ docker run -it --rm -v python-gitlab:latest <command> ...
 
 Bug reports
-===========
+-----------
 
 Please report bugs and feature requests at
 https://github.com/python-gitlab/python-gitlab/issues.
 
 Gitter Community Chat
-=====================
+---------------------
 
 There is a `gitter <https://gitter.im/python-gitlab/Lobby>`_ community chat
 available at https://gitter.im/python-gitlab/Lobby
 
 Documentation
-=============
+-------------
 
 The full documentation for CLI and API is available on `readthedocs
 <http://python-gitlab.readthedocs.org/en/stable/>`_.
 
 Build the docs
---------------
-You can build the documentation using ``sphinx``::
+~~~~~~~~~~~~~~
 
-    pip install sphinx
-    python setup.py build_sphinx
+We use ``tox`` to manage our environment and build the documentation::
 
+    pip install tox
+    tox -e docs
 
 Contributing
-============
+------------
 
 For guidelines for contributing to ``python-gitlab``, refer to `CONTRIBUTING.rst <https://github.com/python-gitlab/python-gitlab/blob/main/CONTRIBUTING.rst>`_.

docs/cli-examples.rst

@@ -0,0 +1,168 @@
+############
+CLI examples
+############
+
+    **Notice:**
+
+        For a complete list of objects and actions available, see :doc:`/cli-objects`.
+
+List the projects (paginated):
+
+.. code-block:: console
+
+   $ gitlab project list
+
+List all the projects:
+
+.. code-block:: console
+
+   $ gitlab project list --all
+
+List all projects of a group:
+
+.. code-block:: console
+
+   $ gitlab group-project list --all --group-id 1
+
+List all projects of a group and its subgroups:
+
+.. code-block:: console
+
+   $ gitlab group-project list --all --include-subgroups true --group-id 1
+
+Limit to 5 items per request, display the 1st page only
+
+.. code-block:: console
+
+   $ gitlab project list --page 1 --per-page 5
+
+Get a specific project (id 2):
+
+.. code-block:: console
+
+   $ gitlab project get --id 2
+
+Get a specific user by id:
+
+.. code-block:: console
+
+   $ gitlab user get --id 3
+
+Create a deploy token for a project:
+
+.. code-block:: console
+
+   $ gitlab -v project-deploy-token create --project-id 2 \
+        --name bar --username root --expires-at "2021-09-09" --scopes "read_repository"
+
+List deploy tokens for a group:
+
+.. code-block:: console
+
+   $ gitlab -v group-deploy-token list --group-id 3
+
+List packages for a project:
+
+.. code-block:: console
+
+   $ gitlab -v project-package list --project-id 3
+
+List packages for a group:
+
+.. code-block:: console
+
+   $ gitlab -v group-package list --group-id 3
+
+Get a specific project package by id:
+
+.. code-block:: console
+
+   $ gitlab -v project-package get --id 1 --project-id 3
+
+Delete a specific project package by id:
+
+.. code-block:: console
+
+   $ gitlab -v project-package delete --id 1 --project-id 3
+
+Upload a generic package to a project:
+
+.. code-block:: console
+
+   $ gitlab generic-package upload --project-id 1 --package-name hello-world \
+        --package-version v1.0.0 --file-name hello.tar.gz --path /path/to/hello.tar.gz
+
+Download a project's generic package:
+
+.. code-block:: console
+
+   $ gitlab generic-package download --project-id 1 --package-name hello-world \
+        --package-version v1.0.0 --file-name hello.tar.gz > /path/to/hello.tar.gz
+
+Get a list of issues for this project:
+
+.. code-block:: console
+
+   $ gitlab project-issue list --project-id 2
+
+Delete a snippet (id 3):
+
+.. code-block:: console
+
+   $ gitlab project-snippet delete --id 3 --project-id 2
+
+Update a snippet:
+
+.. code-block:: console
+
+   $ gitlab project-snippet update --id 4 --project-id 2 \
+       --code "My New Code"
+
+Create a snippet:
+
+.. code-block:: console
+
+   $ gitlab project-snippet create --project-id 2
+   Impossible to create object (Missing attribute(s): title, file-name, code)
+   $ # oops, let's add the attributes:
+   $ gitlab project-snippet create --project-id 2 --title "the title" \
+       --file-name "the name" --code "the code"
+
+Get a specific project commit by its SHA id:
+
+.. code-block:: console
+
+   $ gitlab project-commit get --project-id 2 --id a43290c
+
+Get the signature (e.g. GPG or x509) of a signed commit:
+
+.. code-block:: console
+
+   $ gitlab project-commit signature --project-id 2 --id a43290c
+
+Define the status of a commit (as would be done from a CI tool for example):
+
+.. code-block:: console
+
+   $ gitlab project-commit-status create --project-id 2 \
+       --commit-id a43290c --state success --name ci/jenkins \
+       --target-url http://server/build/123 \
+       --description "Jenkins build succeeded"
+
+Download the artifacts zip archive of a job:
+
+.. code-block:: console
+
+   $ gitlab project-job artifacts --id 10 --project-id 1 > artifacts.zip
+
+Use sudo to act as another user (admin only):
+
+.. code-block:: console
+
+   $ gitlab project create --name user_project1 --sudo username
+
+List values are comma-separated:
+
+.. code-block:: console
+
+   $ gitlab issue list --labels foo,bar