docs(api): describe the list() and all() runners' functions

Liora Milbaum · nejch · commit b6cc3f255532 · 2022-10-09T22:01:52.000+02:00
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -38,3 +38,9 @@ repos:
           - types-PyYAML==6.0.12
           - types-requests==2.28.11
           - types-setuptools==64.0.1
+  - repo: https://github.com/pre-commit/pygrep-hooks
+    rev: v1.9.0
+    hooks:
+      - id: rst-backticks
+      - id: rst-directive-colons
+      - id: rst-inline-touching-normal
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
@@ -93,7 +93,7 @@ To run these tests:
 
 When developing tests it can be a little frustrating to wait for GitLab to spin
 up every run. To prevent the containers from being cleaned up afterwards, pass
-`--keep-containers` to pytest, i.e.:
+``--keep-containers`` to pytest, i.e.:
 
 .. code-block:: bash
 
@@ -116,7 +116,7 @@ The tag must match an exact tag on Docker Hub:
 
 .. code-block:: bash
 
-   # run tests against `nightly` or specific tag
+   # run tests against ``nightly`` or specific tag
    GITLAB_TAG=nightly tox -e api_func_v4
    GITLAB_TAG=12.8.0-ce.0 tox -e api_func_v4
 
diff --git a/docs/api-usage-advanced.rst b/docs/api-usage-advanced.rst
@@ -53,11 +53,11 @@ https://requests.readthedocs.io/en/latest/user/advanced/#proxies
 SSL certificate verification
 ----------------------------
 
-python-gitlab relies on the CA certificate bundle in the `certifi` package
+python-gitlab relies on the CA certificate bundle in the ``certifi`` package
 that comes with the requests library.
 
 If you need python-gitlab to use your system CA store instead, you can provide
-the path to the CA bundle in the `REQUESTS_CA_BUNDLE` environment variable.
+the path to the CA bundle in the ``REQUESTS_CA_BUNDLE`` environment variable.
 
 Reference:
 https://requests.readthedocs.io/en/latest/user/advanced/#ssl-cert-verification
@@ -124,7 +124,7 @@ python-gitlab can automatically retry in such case, when
 ``retry_transient_errors`` argument is set to ``True``.  When enabled,
 HTTP error codes 500 (Internal Server Error), 502 (502 Bad Gateway),
 503 (Service Unavailable), and 504 (Gateway Timeout) are retried. It will retry until reaching
-the `max_retries` value. By default, `retry_transient_errors` is set to `False` and an exception
+the ``max_retries`` value. By default, ``retry_transient_errors`` is set to ``False`` and an exception
 is raised for these errors.
 
 .. code-block:: python
diff --git a/docs/api-usage.rst b/docs/api-usage.rst
@@ -200,7 +200,7 @@ You can print a Gitlab Object. For example:
    # Or in a prettier format.
    project.pprint()
 
-   # Or explicitly via `pformat()`. This is equivalent to the above.
+   # Or explicitly via ``pformat()``. This is equivalent to the above.
    print(project.pformat())
 
 You can also extend the object if the parameter isn't explicitly listed. For example,
@@ -217,16 +217,16 @@ the value on the object is accepted:
 You can get a dictionary representation copy of the Gitlab Object. Modifications made to
 the dictionary will have no impact on the GitLab Object.
 
- * `asdict()` method. Returns a dictionary representation of the Gitlab object.
- * `attributes` property. Returns a dictionary representation of the Gitlab
+ * ``asdict()`` method. Returns a dictionary representation of the Gitlab object.
+ * ``attributes`` property. Returns a dictionary representation of the Gitlab
    object. Also returns any relevant parent object attributes.
 
 .. note::
 
-   `attributes` returns the parent object attributes that are defined in
-   `object._from_parent_attrs`. What this can mean is that for example a `ProjectIssue`
-   object will have a `project_id` key in the dictionary returned from `attributes` but
-   `asdict()` will not.
+   ``attributes`` returns the parent object attributes that are defined in
+   ``object._from_parent_attrs``. What this can mean is that for example a ``ProjectIssue``
+   object will have a ``project_id`` key in the dictionary returned from ``attributes`` but
+   ``asdict()`` will not.
 
 
 .. code-block:: python
@@ -244,7 +244,7 @@ You can get a JSON string represenation of the Gitlab Object. For example:
 
    project = gl.projects.get(1)
    print(project.to_json())
-   # Use arguments supported by `json.dump()`
+   # Use arguments supported by ``json.dump()``
    print(project.to_json(sort_keys=True, indent=4))
 
 Base types
diff --git a/docs/cli-usage.rst b/docs/cli-usage.rst
@@ -219,7 +219,7 @@ Example for a `pass <https://www.passwordstore.org>`_ helper with a wrapper scri
    private_token = helper: /path/to/helper.sh
    timeout = 1
 
-In `/path/to/helper.sh`:
+In ``/path/to/helper.sh``:
 
 .. code-block:: bash
 
@@ -332,7 +332,7 @@ tcsh
 
 .. code-block:: console
 
-   eval `register-python-argcomplete --shell tcsh gitlab`
+   eval ``register-python-argcomplete --shell tcsh gitlab``
 
 fish
 ----
diff --git a/docs/gl_objects/runners.rst b/docs/gl_objects/runners.rst
@@ -28,16 +28,20 @@ Reference
 Examples
 --------
 
-Use the ``list()`` and ``all()`` methods to list runners.
+Use the ``runners.list()`` and ``runners_all.list()`` methods to list runners.
+``runners.list()`` - Get a list of specific runners available to the user
+``runners_all.list()``  - Get a list of all runners in the GitLab instance 
+(specific and shared). Access is restricted to users with administrator access.
+
 
 Both methods accept a ``scope`` parameter to filter the list. Allowed values
 for this parameter are:
 
 * ``active``
 * ``paused``
 * ``online``
-* ``specific`` (``all()`` only)
-* ``shared`` (``all()`` only)
+* ``specific`` (``runners_all.list()`` only)
+* ``shared`` (``runners_all.list()`` only)
 
 .. note::
 
