docs: switch to Furo and refresh introduction pagesdocs/furo-cleanup

7 files changed, 47 insertions, 101 deletions

diff --git a/README.rst b/README.rst
index b59549c..838943c 100644
--- a/README.rst
+++ b/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>`_.
diff --git a/docs/_templates/breadcrumbs.html b/docs/_templates/breadcrumbs.html
deleted file mode 100644
index cdb05a9..0000000
--- a/docs/_templates/breadcrumbs.html
+++ /dev/null
@@ -1,24 +0,0 @@
-{# Support for Sphinx 1.3+ page_source_suffix, but don't break old builds. #}
-
-{% if page_source_suffix %} 
-{% set suffix = page_source_suffix %}
-{% else %}
-{% set suffix = source_suffix %}
-{% endif %}
-
-<div role="navigation" aria-label="breadcrumbs navigation">
-  <ul class="wy-breadcrumbs">
-    <li><a href="{{ pathto(master_doc) }}">Docs</a> &raquo;</li>
-      {% for doc in parents %}
-          <li><a href="{{ doc.link|e }}">{{ doc.title }}</a> &raquo;</li>
-      {% endfor %}
-    <li>{{ title }}</li>
-      <li class="wy-breadcrumbs-aside">
-        {% if pagename != "search" %}
-            <a href="https://github.com/python-gitlab/python-gitlab/blob/main/{{ conf_py_path }}{{ pagename }}{{ suffix }}" class="fa fa-github"> Edit on GitHub</a>
-            | <a href="https://github.com/python-gitlab/python-gitlab/issues/new?title=Documentation+bug&body=%0A%0A------%0AIn+page:+{{ pagename }}{{ suffix }}">Report a bug</a>
-        {% endif %}
-      </li>
-  </ul>
-  <hr/>
-</div>
diff --git a/docs/cli-usage.rst b/docs/cli-usage.rst
index 6dbce5d..4f89964 100644
--- a/docs/cli-usage.rst
+++ b/docs/cli-usage.rst
@@ -1,6 +1,6 @@
-####################
-``gitlab`` CLI usage
-####################
+############################
+Getting started with the CLI
+############################
 
 ``python-gitlab`` provides a :command:`gitlab` command-line tool to interact
 with GitLab servers.
diff --git a/docs/conf.py b/docs/conf.py
index 2a1b292..a801953 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -17,12 +17,14 @@ from __future__ import unicode_literals
 
 import os
 import sys
+from datetime import datetime
 
 sys.path.append("../")
 sys.path.append(os.path.dirname(__file__))
 import gitlab  # noqa: E402. Needed purely for readthedocs' build
 
 on_rtd = os.environ.get("READTHEDOCS", None) == "True"
+year = datetime.now().year
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -57,11 +59,13 @@ source_suffix = {".rst": "restructuredtext", ".md": "markdown"}
 # source_encoding = 'utf-8-sig'
 
 # The master toctree document.
-master_doc = "index"
+root_doc = "index"
 
 # General information about the project.
 project = "python-gitlab"
-copyright = "2013-2018, Gauvain Pocentek, Mika Mäenpää"
+copyright = (
+    f"2013-2018, Gauvain Pocentek, Mika Mäenpää.\n2018-{year}, python-gitlab team"
+)
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -101,9 +105,6 @@ exclude_patterns = ["_build"]
 # output. They are ignored by default.
 # show_authors = False
 
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = "sphinx"
-
 # A list of ignored prefixes for module index sorting.
 # modindex_common_prefix = []
 
@@ -115,15 +116,7 @@ pygments_style = "sphinx"
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = "default"
-if not on_rtd:  # only import and set the theme if we're building docs locally
-    try:
-        import sphinx_rtd_theme
-
-        html_theme = "sphinx_rtd_theme"
-        html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-    except ImportError:  # Theme not found, use default
-        pass
+html_theme = "furo"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -135,7 +128,7 @@ if not on_rtd:  # only import and set the theme if we're building docs locally
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-# html_title = None
+html_title = f"{project} <small>v{release}</small>"
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 # html_short_title = None
diff --git a/docs/index.rst b/docs/index.rst
index 3f8672b..02ff8eb 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,23 +1,15 @@
-.. python-gitlab documentation master file, created by
-   sphinx-quickstart on Mon Dec  8 15:17:39 2014.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Welcome to python-gitlab's documentation!
-=========================================
-
-Contents:
+.. include:: ../README.rst
 
 .. toctree::
-   :maxdepth: 2
+   :caption: Table of Contents
+   :hidden:
 
-   install
    cli-usage
    api-usage
-   faq
    api-objects
    api/gitlab
    cli-objects
+   faq
    changelog
    release-notes
 
diff --git a/docs/install.rst b/docs/install.rst
deleted file mode 100644
index b8672bb..0000000
--- a/docs/install.rst
+++ /dev/null
@@ -1,26 +0,0 @@
-############
-Installation
-############
-
-``python-gitlab`` is compatible with Python 3.7+.
-
-Use :command:`pip` to install the latest stable version of ``python-gitlab``:
-
-.. code-block:: console
-
-   $ pip install --upgrade python-gitlab
-
-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 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
diff --git a/requirements-docs.txt b/requirements-docs.txt
index 7d4c471..1fa1e7e 100644
--- a/requirements-docs.txt
+++ b/requirements-docs.txt
@@ -1,4 +1,5 @@
 -r requirements.txt
+furo
 jinja2
 myst-parser
 sphinx==4.3.2