Add documentation

Change-Id: Ia07830ad9d1be4c684031866d38a589b28a6e580
Signed-off-by: Jaromir Wysoglad <jwysogla@redhat.com>

.zuul.yaml

@@ -30,6 +30,7 @@
     queue: telemetry
     templates:
       - openstack-python3-jobs
+      - publish-openstack-docs-pti
       - check-requirements
       - release-notes-jobs-python3
     check:

CONTRIBUTING.rst

@@ -0,0 +1,17 @@
+If you would like to contribute to the development of OpenStack, you must
+follow the steps in this page:
+
+   https://docs.openstack.org/infra/manual/developers.html
+
+If you already have a good understanding of how the system works and your
+OpenStack accounts are set up, you can skip to the development workflow
+section of this documentation to learn how changes to OpenStack should be
+submitted for review via the Gerrit tool:
+
+   https://docs.openstack.org/infra/manual/developers.html#development-workflow
+
+Pull requests submitted through GitHub will be ignored.
+
+Bugs should be filed on Launchpad, not GitHub:
+
+   https://storyboard.openstack.org/#!/project/openstack/python-observabilityclient

doc/requirements.txt

@@ -1,3 +1,3 @@
 sphinx>=2.1.1 # BSD
 openstackdocstheme>=2.2.1 # Apache-2.0
-reno>=1.6.2 # Apache-2.0
+reno>=3.1.0 # Apache-2.0

doc/source/api.rst

@@ -0,0 +1,39 @@
+The :mod:`observabilityclient` Python API
+=========================================
+
+.. module:: observabilityclient
+   :synopsis: A client for the Prometheus API.
+
+.. currentmodule:: observabilityclient
+
+Usage
+-----
+
+To use observabilityclient in a project::
+
+    >>> from observabilityclient import client
+    >>> obs_client = client.Client('1', session, adapter_options=adapter_opts)
+    >>> obs_client.query.list()
+
+To have queries scoped to a single project (for restricting unprivileged
+access to metrics from other projects)::
+
+    >>> # Assuming you have client created following previous example
+    >>> from observabilityclient import rbac as obsc_rbac
+    >>> promQLRbac = obsc_rbac.PromQLRbac(
+    >>>    obs_client.prometheus_client,
+    >>>    project_id
+    >>> )
+    >>> scoped_query = promQLRbac.modify_query(query)
+
+Reference
+---------
+
+For more information, see the reference:
+
+.. toctree::
+   :maxdepth: 2
+
+   ref/v1/index
+   ref/index
+

doc/source/conf.py

@@ -0,0 +1,122 @@
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+import sys
+
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+ROOT = os.path.abspath(os.path.join(BASE_DIR, "..", ".."))
+
+sys.path.insert(0, ROOT)
+sys.path.insert(0, BASE_DIR)
+
+
+def gen_ref(ver, title, names):
+    refdir = os.path.join(BASE_DIR, "ref")
+    pkg = "observabilityclient"
+    if ver:
+        pkg = "%s.%s" % (pkg, ver)
+        refdir = os.path.join(refdir, ver)
+    if not os.path.exists(refdir):
+        os.makedirs(refdir)
+    idxpath = os.path.join(refdir, "index.rst")
+    with open(idxpath, "w") as idx:
+        idx.write(("%(title)s\n"
+                   "%(signs)s\n"
+                   "\n"
+                   ".. toctree::\n"
+                   "   :maxdepth: 1\n"
+                   "\n") % {"title": title, "signs": "=" * len(title)})
+        for name in names:
+            idx.write("   %s\n" % name)
+            rstpath = os.path.join(refdir, "%s.rst" % name)
+            with open(rstpath, "w") as rst:
+                rst.write(("%(title)s\n"
+                           "%(signs)s\n"
+                           "\n"
+                           ".. automodule:: %(pkg)s.%(name)s\n"
+                           "   :members:\n"
+                           "   :undoc-members:\n"
+                           "   :show-inheritance:\n"
+                           "   :noindex:\n")
+                          % {"title": " ".join([n.capitalize()
+                                                for n in name.split("_")]),
+                             "signs": "=" * len(name),
+                             "pkg": pkg, "name": name})
+
+gen_ref("v1", "Version 1 API", ["client", "python_api"])
+gen_ref("", "rbac", ["rbac"])
+
+# -- General configuration ----------------------------------------------------
+
+# 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',
+    'openstackdocstheme',
+    #'sphinx.ext.intersphinx',
+]
+
+# autodoc generation is a bit aggressive and a nuisance when doing heavy
+# text edit cycles.
+# execute "export SPHINX_DEBUG=1" in your terminal to disable
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# openstackdocstheme options
+openstackdocs_repo_name = 'openstack/python-observabilityclient'
+openstackdocs_bug_project = 'python-observabilityclient'
+openstackdocs_bug_tag = ''
+copyright = u'2025, OpenStack Foundation'
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = True
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'native'
+
+# -- Options for HTML output --------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+# html_theme_path = ["."]
+# html_theme = '_theme'
+# html_static_path = ['static']
+html_theme = 'openstackdocs'
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = ['_theme']
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'observabilityclientdoc'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass
+# [howto/manual]).
+latex_documents = [
+    ('index',
+     'observabilityclient.tex',
+     u'observabilityclient Documentation',
+     u'OpenStack Foundation', 'manual'),
+]
+
+# Example configuration for intersphinx: refer to the Python standard library.
+#intersphinx_mapping = {'http://docs.python.org/': None}

doc/source/contributing.rst

@@ -0,0 +1,4 @@
+============
+Contributing
+============
+.. include:: ../../CONTRIBUTING.rst

doc/source/index.rst

@@ -0,0 +1,26 @@
+Python bindings to the Prometheus API
+=====================================
+This is an OpenStackClient (OSC) plugin that implements commands for
+management of Prometheus.
+There's :doc:`a Python API <api>` (the :mod:`observabilityclient` module),
+and a :doc:`command-line client <shell>`.
+Each implements the same subset of Prometheus API.
+
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 2
+
+   installation
+   shell
+   api
+   contributing
+
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

doc/source/installation.rst

@@ -0,0 +1,7 @@
+============
+Installation
+============
+
+At the command line::
+
+    $ pip install python-observabilityclient

doc/source/shell.rst

@@ -0,0 +1,38 @@
+The :program:`observabilityclient` openstack client extension
+=============================================================
+
+.. program:: observabilityclient
+.. highlight:: bash
+
+The :program:`observabilityclient` openstack client extension interacts with Prometheus API
+from the command line. It supports the same subset of Prometheus API as the
+observabilityclient python API.
+
+.. warning::
+
+   This client commands conflict with the gnocchiclient commands.
+   Make sure to have only one of these clients installed at a time
+
+All shell commands take the form::
+
+    openstack metric <command> [arguments...]
+
+Run :program:`openstack metric --help` to get a full list of all possible commands,
+and run :program:`openstack metric <command> --help` to get detailed help for that
+command.
+
+Examples
+--------
+
+List all accessible metrics::
+
+    openstack metric list
+
+Show details of the ceilometer_cpu metric::
+
+    openstack metric show ceilometer_cpu
+
+Send any PromQL query::
+
+    openstack metric query 'ceilometer_cpu{counter="cpu",job="ceilometer"} + on (counter, job) sum by (counter) (ceilometer_memory{label="baz",counter="NS",pod="POD"})'
+

tox.ini

@@ -47,6 +47,14 @@ commands =
     bash tools/fix_ca_bundle.sh
     stestr run --slowest {posargs} --test-path {env:OS_TEST_PATH}
 
+[testenv:docs]
+deps =
+    -c{env:TOX_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master}
+    -r{toxinidir}/requirements.txt
+    -r{toxinidir}/doc/requirements.txt
+commands = sphinx-build --keep-going -b html doc/source doc/build/html
+
+
 [flake8]
 show-source = True
 # A002 argument "input" is shadowing a python builtin