diff options
| -rw-r--r-- | README.rst | 52 | ||||
| -rw-r--r-- | docs/_templates/breadcrumbs.html | 24 | ||||
| -rw-r--r-- | docs/cli-usage.rst | 6 | ||||
| -rw-r--r-- | docs/conf.py | 23 | ||||
| -rw-r--r-- | docs/index.rst | 16 | ||||
| -rw-r--r-- | docs/install.rst | 26 | ||||
| -rw-r--r-- | requirements-docs.txt | 1 |
7 files changed, 47 insertions, 101 deletions
@@ -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> »</li> - {% for doc in parents %} - <li><a href="{{ doc.link|e }}">{{ doc.title }}</a> »</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 |