diff options
| -rw-r--r-- | README.rst | 52 | ||||
| -rw-r--r-- | docs/_templates/breadcrumbs.html | 24 | ||||
| -rw-r--r-- | docs/cli-examples.rst | 168 | ||||
| -rw-r--r-- | docs/cli-usage.rst | 174 | ||||
| -rw-r--r-- | docs/conf.py | 23 | ||||
| -rw-r--r-- | docs/index.rst | 17 | ||||
| -rw-r--r-- | docs/install.rst | 26 | ||||
| -rw-r--r-- | requirements-docs.txt | 1 |
8 files changed, 216 insertions, 269 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-examples.rst b/docs/cli-examples.rst new file mode 100644 index 0000000..9b0aff8 --- /dev/null +++ b/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
\ No newline at end of file diff --git a/docs/cli-usage.rst b/docs/cli-usage.rst index 6dbce5d..20e0736 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. @@ -293,174 +293,6 @@ Example: $ gitlab -o yaml -f id,permissions -g elsewhere -c /tmp/gl.cfg project list -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 - Reading values from files ------------------------- 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..22b926d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,25 +1,18 @@ -.. 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 + cli-examples api-objects api/gitlab cli-objects changelog release-notes + faq Indices and tables 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 |