Skip to content

Commit ee6b024

Browse files
nejchJohnVillalovos
nejch
authored and
JohnVillalovos
committed
docs: switch to Furo and refresh introduction pages
1 parent 1582387 commit ee6b024

File tree

8 files changed

+216
-269
lines changed

8 files changed

+216
-269
lines changed

‎README.rst

Lines changed: 31 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
python-gitlab
2+
=============
3+
14
.. image:: https://github.com/python-gitlab/python-gitlab/workflows/Test/badge.svg
25
:target: https://github.com/python-gitlab/python-gitlab/actions
36

@@ -19,32 +22,39 @@
1922
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
2023
:target: https://github.com/python/black
2124

22-
Python GitLab
23-
=============
24-
2525
``python-gitlab`` is a Python package providing access to the GitLab server API.
2626

2727
It supports the v4 API of GitLab, and provides a CLI tool (``gitlab``).
2828

2929
Installation
30-
============
31-
32-
Requirements
3330
------------
3431

35-
python-gitlab depends on:
32+
As of 3.0.0, ``python-gitlab`` is compatible with Python 3.7+.
33+
34+
Use ``pip`` to install the latest stable version of ``python-gitlab``:
35+
36+
.. code-block:: console
3637
37-
* `python-requests <https://2.python-requests.org/en/latest/>`_
38+
$ pip install --upgrade python-gitlab
3839
39-
Install with pip
40-
----------------
40+
The current development version is available on both `GitHub.com
41+
<https://github.com/python-gitlab/python-gitlab>`__ and `GitLab.com
42+
<https://gitlab.com/python-gitlab/python-gitlab>`__, and can be
43+
installed directly from the git repository:
4144

4245
.. code-block:: console
4346
44-
pip install python-gitlab
47+
$ pip install git+https://github.com/python-gitlab/python-gitlab.git
48+
49+
From GitLab:
50+
51+
.. code-block:: console
52+
53+
$ pip install git+https://gitlab.com/python-gitlab/python-gitlab.git
54+
4555
4656
Using the docker image
47-
======================
57+
----------------------
4858

4959
You can run the Docker image directly from the GitLab registry:
5060

@@ -65,7 +75,7 @@ You can also mount your own config file:
6575
$ docker run -it --rm -v /path/to/python-gitlab.cfg:/etc/python-gitlab.cfg registry.gitlab.com/python-gitlab/python-gitlab:latest <command> ...
6676
6777
Building the image
68-
------------------
78+
~~~~~~~~~~~~~~~~~~
6979

7080
To build your own image from this repository, run:
7181

@@ -80,32 +90,32 @@ Run your own image:
8090
$ docker run -it --rm -v python-gitlab:latest <command> ...
8191
8292
Bug reports
83-
===========
93+
-----------
8494

8595
Please report bugs and feature requests at
8696
https://github.com/python-gitlab/python-gitlab/issues.
8797

8898
Gitter Community Chat
89-
=====================
99+
---------------------
90100

91101
There is a `gitter <https://gitter.im/python-gitlab/Lobby>`_ community chat
92102
available at https://gitter.im/python-gitlab/Lobby
93103

94104
Documentation
95-
=============
105+
-------------
96106

97107
The full documentation for CLI and API is available on `readthedocs
98108
<http://python-gitlab.readthedocs.org/en/stable/>`_.
99109

100110
Build the docs
101-
--------------
102-
You can build the documentation using ``sphinx``::
111+
~~~~~~~~~~~~~~
103112

104-
pip install sphinx
105-
python setup.py build_sphinx
113+
We use ``tox`` to manage our environment and build the documentation::
106114

115+
pip install tox
116+
tox -e docs
107117

108118
Contributing
109-
============
119+
------------
110120

111121
For guidelines for contributing to ``python-gitlab``, refer to `CONTRIBUTING.rst <https://github.com/python-gitlab/python-gitlab/blob/main/CONTRIBUTING.rst>`_.

‎docs/_templates/breadcrumbs.html

Lines changed: 0 additions & 24 deletions
This file was deleted.

‎docs/cli-examples.rst

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
############
2+
CLI examples
3+
############
4+
5+
**Notice:**
6+
7+
For a complete list of objects and actions available, see :doc:`/cli-objects`.
8+
9+
List the projects (paginated):
10+
11+
.. code-block:: console
12+
13+
$ gitlab project list
14+
15+
List all the projects:
16+
17+
.. code-block:: console
18+
19+
$ gitlab project list --all
20+
21+
List all projects of a group:
22+
23+
.. code-block:: console
24+
25+
$ gitlab group-project list --all --group-id 1
26+
27+
List all projects of a group and its subgroups:
28+
29+
.. code-block:: console
30+
31+
$ gitlab group-project list --all --include-subgroups true --group-id 1
32+
33+
Limit to 5 items per request, display the 1st page only
34+
35+
.. code-block:: console
36+
37+
$ gitlab project list --page 1 --per-page 5
38+
39+
Get a specific project (id 2):
40+
41+
.. code-block:: console
42+
43+
$ gitlab project get --id 2
44+
45+
Get a specific user by id:
46+
47+
.. code-block:: console
48+
49+
$ gitlab user get --id 3
50+
51+
Create a deploy token for a project:
52+
53+
.. code-block:: console
54+
55+
$ gitlab -v project-deploy-token create --project-id 2 \
56+
--name bar --username root --expires-at "2021-09-09" --scopes "read_repository"
57+
58+
List deploy tokens for a group:
59+
60+
.. code-block:: console
61+
62+
$ gitlab -v group-deploy-token list --group-id 3
63+
64+
List packages for a project:
65+
66+
.. code-block:: console
67+
68+
$ gitlab -v project-package list --project-id 3
69+
70+
List packages for a group:
71+
72+
.. code-block:: console
73+
74+
$ gitlab -v group-package list --group-id 3
75+
76+
Get a specific project package by id:
77+
78+
.. code-block:: console
79+
80+
$ gitlab -v project-package get --id 1 --project-id 3
81+
82+
Delete a specific project package by id:
83+
84+
.. code-block:: console
85+
86+
$ gitlab -v project-package delete --id 1 --project-id 3
87+
88+
Upload a generic package to a project:
89+
90+
.. code-block:: console
91+
92+
$ gitlab generic-package upload --project-id 1 --package-name hello-world \
93+
--package-version v1.0.0 --file-name hello.tar.gz --path /path/to/hello.tar.gz
94+
95+
Download a project's generic package:
96+
97+
.. code-block:: console
98+
99+
$ gitlab generic-package download --project-id 1 --package-name hello-world \
100+
--package-version v1.0.0 --file-name hello.tar.gz > /path/to/hello.tar.gz
101+
102+
Get a list of issues for this project:
103+
104+
.. code-block:: console
105+
106+
$ gitlab project-issue list --project-id 2
107+
108+
Delete a snippet (id 3):
109+
110+
.. code-block:: console
111+
112+
$ gitlab project-snippet delete --id 3 --project-id 2
113+
114+
Update a snippet:
115+
116+
.. code-block:: console
117+
118+
$ gitlab project-snippet update --id 4 --project-id 2 \
119+
--code "My New Code"
120+
121+
Create a snippet:
122+
123+
.. code-block:: console
124+
125+
$ gitlab project-snippet create --project-id 2
126+
Impossible to create object (Missing attribute(s): title, file-name, code)
127+
$ # oops, let's add the attributes:
128+
$ gitlab project-snippet create --project-id 2 --title "the title" \
129+
--file-name "the name" --code "the code"
130+
131+
Get a specific project commit by its SHA id:
132+
133+
.. code-block:: console
134+
135+
$ gitlab project-commit get --project-id 2 --id a43290c
136+
137+
Get the signature (e.g. GPG or x509) of a signed commit:
138+
139+
.. code-block:: console
140+
141+
$ gitlab project-commit signature --project-id 2 --id a43290c
142+
143+
Define the status of a commit (as would be done from a CI tool for example):
144+
145+
.. code-block:: console
146+
147+
$ gitlab project-commit-status create --project-id 2 \
148+
--commit-id a43290c --state success --name ci/jenkins \
149+
--target-url http://server/build/123 \
150+
--description "Jenkins build succeeded"
151+
152+
Download the artifacts zip archive of a job:
153+
154+
.. code-block:: console
155+
156+
$ gitlab project-job artifacts --id 10 --project-id 1 > artifacts.zip
157+
158+
Use sudo to act as another user (admin only):
159+
160+
.. code-block:: console
161+
162+
$ gitlab project create --name user_project1 --sudo username
163+
164+
List values are comma-separated:
165+
166+
.. code-block:: console
167+
168+
$ gitlab issue list --labels foo,bar

0 commit comments

Comments
 (0)