Merge pull request #1209 from python-gitlab/docs/cli-reference-page

docs(cli): add auto-generated CLI reference

docs/api/gitlab.rst

@@ -1,5 +1,5 @@
-gitlab package
-==============
+API reference (``gitlab`` package)
+==================================
 
 Subpackages
 -----------

docs/cli-objects.rst

@@ -0,0 +1,17 @@
+##################################
+CLI reference (``gitlab`` command)
+##################################
+
+.. warning::
+
+    The following is a complete, auto-generated list of subcommands available
+    via the :command:`gitlab` command-line tool. Some of the actions may
+    currently not work as expected or lack functionality available via the API.
+
+    Please see the existing `list of CLI related issues`_, or open a new one if
+    it is not already listed there.
+
+.. _list of CLI related issues: https://github.com/python-gitlab/python-gitlab/issues?q=is%3Aopen+is%3Aissue+label%3Acli
+
+.. autoprogram:: gitlab.cli:docs()
+   :prog: gitlab

docs/cli.rst → docs/cli-usage.rst

@@ -180,6 +180,10 @@ Example:
 Examples
 ========
 
+    **Notice:**
+
+        For a complete list of objects and actions available, see :doc:`/cli-objects`.
+
 List the projects (paginated):
 
 .. code-block:: console

docs/conf.py

@@ -39,7 +39,12 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.autosummary", "ext.docstrings"]
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "ext.docstrings",
+    "sphinxcontrib.autoprogram",
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

docs/index.rst

@@ -12,14 +12,15 @@ Contents:
    :maxdepth: 2
 
    install
-   cli
+   cli-usage
    api-usage
    faq
-   switching-to-v4
    api-objects
    api/gitlab
+   cli-objects
    release_notes
    changelog
+   switching-to-v4
 
 
 Indices and tables

gitlab/cli.py

@@ -149,6 +149,20 @@ def _parse_value(v):
     return v
 
 
+def docs():
+    """
+    Provide a statically generated parser for sphinx only, so we don't need
+    to provide dummy gitlab config for readthedocs.
+    """
+    if "sphinx" not in sys.modules:
+        sys.exit("Docs parser is only intended for build_sphinx")
+
+    parser = _get_base_parser(add_help=False)
+    cli_module = importlib.import_module("gitlab.v4.cli")
+
+    return _get_parser(cli_module)
+
+
 def main():
     if "--version" in sys.argv:
         print(gitlab.__version__)

rtd-requirements.txt

@@ -1,3 +1,5 @@
 -r requirements.txt
 jinja2
 sphinx==3.2.1
+sphinx_rtd_theme
+sphinxcontrib-autoprogram

test-requirements.txt

@@ -1,9 +1,6 @@
 coverage
 httmock
-jinja2
 mock
 pytest
 pytest-cov
-sphinx==3.2.1
-sphinx_rtd_theme
 responses

tox.ini

@@ -44,6 +44,7 @@ max-line-length = 88
 ignore = H501,H803
 
 [testenv:docs]
+deps = -r{toxinidir}/rtd-requirements.txt
 commands = python setup.py build_sphinx
 
 [testenv:cover]