diff --git a/docs/api/gitlab.rst b/docs/api/gitlab.rst index 1dabad2a5..0377b8752 100644 --- a/docs/api/gitlab.rst +++ b/docs/api/gitlab.rst @@ -1,5 +1,5 @@ -gitlab package -============== +API reference (``gitlab`` package) +================================== Subpackages ----------- diff --git a/docs/cli-objects.rst b/docs/cli-objects.rst new file mode 100644 index 000000000..d6648f6a4 --- /dev/null +++ b/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 diff --git a/docs/cli.rst b/docs/cli-usage.rst similarity index 98% rename from docs/cli.rst rename to docs/cli-usage.rst index 95f706250..10fd73afe 100644 --- a/docs/cli.rst +++ b/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 diff --git a/docs/conf.py b/docs/conf.py index a5e5406fa..681af2237 100644 --- a/docs/conf.py +++ b/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"] diff --git a/docs/index.rst b/docs/index.rst index 9c8cfd3ef..22f4c9a61 100644 --- a/docs/index.rst +++ b/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 diff --git a/gitlab/cli.py b/gitlab/cli.py index d356d162a..ff98a4fb8 100644 --- a/gitlab/cli.py +++ b/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__) diff --git a/rtd-requirements.txt b/rtd-requirements.txt index 41c10ba14..a91dd8fb9 100644 --- a/rtd-requirements.txt +++ b/rtd-requirements.txt @@ -1,3 +1,5 @@ -r requirements.txt jinja2 sphinx==3.2.1 +sphinx_rtd_theme +sphinxcontrib-autoprogram diff --git a/test-requirements.txt b/test-requirements.txt index 94890f9b9..8d61ad154 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -1,9 +1,6 @@ coverage httmock -jinja2 mock pytest pytest-cov -sphinx==3.2.1 -sphinx_rtd_theme responses diff --git a/tox.ini b/tox.ini index 92196e53e..45f365d67 100644 --- a/tox.ini +++ b/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]