Metadata-Version: 2.4
Name: grian-ui
Version: 0.1.0
Summary: A horizon dashboard plugin for telemetry visualization
Author-email: OpenStack <openstack-discuss@lists.openstack.org>
License-Expression: Apache-2.0
Project-URL: Homepage, https://opendev.org/openstack/grian-ui
Project-URL: Documentation, https://docs.openstack.org/grian-ui/latest/
Project-URL: Repository, https://opendev.org/openstack/grian-ui
Project-URL: Issues, https://bugs.launchpad.net/grian-ui
Project-URL: Changelog, https://docs.openstack.org/releasenotes/grian-ui/
Keywords: openstack,horizon,telemetry
Classifier: Environment :: OpenStack
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX :: Linux
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Description-Content-Type: text/x-rst
License-File: AUTHORS
Dynamic: license-file

============================================
grian-ui - telemetry visualization dashboard
============================================

* Free software: Apache license
* Documentation: https://docs.openstack.org/grian-ui/latest/
* Release notes: https://docs.openstack.org/releasenotes/grian-ui/
* Source: https://opendev.org/openstack/grian-ui
* Bugs: https://bugs.launchpad.net/grian-ui


..
   TODO: move to contributor docs.

Making Changes & Contributing
=============================

This project uses `pre-commit`_, and `tox`_
please make sure to install them before making any changes::

    cd grian_ui
    python3 -m venv .venv
    . .venv/bin/activate
    python3 -m pip install pre-commit tox git-review
    pre-commit install --install-hooks

It is a good practice for maintainers to update the hooks
to the latest version every few months. this can be done with::

    pre-commit autoupdate

and submitting a commit.
when updating the hooks it may be necessary to address new issues
found. To make ci pass these issues should be fixed in the same
commit that makes the change however you should avoid making unrelated
fixes in the same patch.

.. _pre-commit: https://pre-commit.com/
.. _tox: https://tox.wiki

This project uses tox to execute tests, build docs and automate
other development task that are not suitable for automation via pre-commit.


Running Tests
-------------

This repo currently has 3 type of tests but more may follow

First unit tests can be run with your envs default python like this ::

  ``tox -e py3``  or  ``tox -e unit``

it also possible to you a non default python version by specifying a version sufix ::

  tox -e py312

The second  type of testing is functional testing. Where as unit
tests should be short and test individual functions. Functional
tests should avoid mocking code in the plugin but can use fixtures
or other fakes/proxy to replace external systems like a fake datasoures
that returns static data or emulates an openstack service like keystone.

functional tests can be run in a similar way to unit tests ::

  ``tox -e functional`` or ``tox -e functional-py312``


The third type of testing we have today are style/lint checks.
there are 3 ways to run these checks first with tox ::

  ``tox -e pep8`` or ``tox -e lint``

by convention in openstack we use a ``pep8`` tox env to execute all
our style and linting checks not just pep8. in many other communities
this is often called ``lint`` so we support both.

internally both targets are identical and call pre-commit to run the
style checks. So the third way to run the style checks is with
pre-commit directly::

  ``pre-commit run -a``

or if you have the hooks installed they will run automatically
when you commit a change. If you ever want to override that behavior
you can do::

  #skip all checks
  git commit --no-verify

  or

  # skip a single check
  SKIP=hacking git commit

 .. NOTE::

    unit, functional and style checks are enforced by our zuul
    CI system so if they don't pass your code cant merge.
    CI just run the tox command the same as you can do locally
    so its encouraged to run them locally first.


DOCS
----

docs are built via tox envs that wrap a tool called sphinx.
At present we have two types of docs, general docs are stored in
the doc folder and release notes that are generated by the ``reno``
tool are stored in the releasenotes directory.
As can be seen form this README we use a format called
`reStructuredText`_ to write all our docs.

.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

The main docs can be built with either ``tox -e docs`` or ``tox -e pdf-docs``
depending on the desired format. Note that to be able to build PDF docs in
particular you may need to install binary depencies on your system.
These can be found in ``bindep.txt`` in the ``doc`` and ``pdf-docs`` profiles.

The second type of docs we have are the release notes. New release-notes
can be added by executing ``tox -e venv -- reno new your-note-name-here``
and built with ``tox -e releasenotes``


.. NOTE::

   The venv example above demonstrates that many tox envs support taking
   additional parameter that can be passed to the underlying tools. In the
   case of the venv target it will create a virtual enve with all the
   runtime test and docs depencies installed so tools such as sphinx,
   reno, manage.py can all be used from that env. For the unit and
   functional envs additional parameters can be passed to stestr to
   contol how tests are run such as a text regex.

Running Grian-UI for development
================================

Work in progress.

This will evolve overtime but as of this moment its possible
to run Grian-UI in horizon by running ``tox -e runserver``.
This can also be done manually via ``tox -e venv -- ./manage.py runserver``

For this to be useful you will need to have openstack which can
be deployed with devstack or any other tool. A sample
`local.conf <devstack/local.conf-all-in-one>` is provided in the
devstack plugin.


This local.conf expect the following file at /opt/stack/prometheus.yml ::

  global:
    scrape_interval: 10s
  scrape_configs:
    - job_name: "node"
      static_configs:
        - targets: ["localhost:3000"]

..
   TODO: enable Grian-UI when we add any content.
   and move the devstack example to the devstack plugin

if you are running devstack on a remote vm you can forward the development server endpoint locally using the following command ::

  ssh -N -L 8000:localhost:8000 <user@host>

This will create an ssh session and forward ``localhost:8000`` on the
remote system to localhost:8000 on your local system.
`-N` prevents allocating a shell for the ssh session while not required
it recommended to use a dedicated ssh command to forward ports.
