diff --git a/.zuul.yaml b/.zuul.yaml
index 582d873..9c0c641 100644
--- a/.zuul.yaml
+++ b/.zuul.yaml
@@ -86,6 +86,7 @@
- openstack-python-jobs
- openstack-python3-train-jobs
- release-notes-jobs-python3
+ - publish-openstack-docs-pti
check:
jobs:
- ironic-prometheus-exporter-redfish
diff --git a/README.rst b/README.rst
index 84786f7..67d3fc2 100644
--- a/README.rst
+++ b/README.rst
@@ -1,9 +1,8 @@
Ironic Prometheus Exporter
==========================
-Overview
---------
-Tool to expose hardware sensor data in the `Prometheus `_ format through an HTTP endpoint.
+Ironic Prometheus Exporter is a Tool to expose hardware sensor data in the
+`Prometheus `_ format through an HTTP endpoint.
The hardware sensor data come from bare metal machines deployed
using `OpenStack Bare Metal Service (ironic) `_.
@@ -12,87 +11,3 @@ using `OpenStack Bare Metal Service (ironic)
- $ epi group show oslo.messaging.notify.drivers
-
-
-- Output in case of a successful instalation: `prometheus_exporter` is listed in the `Name` column and the `Error` column should be empty.
-- Output in case of an unsuccessful instalation: `prometheus_exporter` is listed in the `Name` column and the `Error` column will have more information.
-
-
-Configuration
--------------
-
-After install the driver you will need to update the `ironic.conf` and add the following information:
-
-::
-
- [conductor]
- send_sensor_data=true
-
- [oslo_messaging_notifications]
- driver = prometheus_exporter
- transport_url = fake://
- location=/tmp/ironic_prometheus_exporter
-
-
-
-Running exporter application
-----------------------------
-
-The Flask Application is responsible to merge all the metrics files present in the directory
-set in `[oslo_messaging_notifications]/location`.
-
-.. note:: If you want to deploy in production please check the Flask `documentation `_
-
-To run the Flask Application follow the steps listed below:
-1 - open the repository directory
-::
-
- $ cd ironic-prometheus-exporter/
-
-2- set the `FLASK_*` environment variables and the location of the `ironic.conf` file.
-::
-
- $ export IRONIC_CONFIG=/etc/ironic/ironic.conf
- $ export FLASK_APP=ironic_prometheus_exporter/app/exporter.py
- $ export FLASK_RUN_HOST=$HOST_IP
- $ export FLASK_RUN_PORT=5000
-
-3- run the Flask Application
-::
-
-$ python -m flask run &
-
-
-**Running under uWSGI**
-
-Reproduce the Steps 1 and 2 (You don't need to set `FLASK_APP` variable) and run the command below:
-::
-
-$ uwsgi --plugin python --http-socket ${FLASK_RUN_HOST}:${FLASK_RUN_PORT} --module ironic_prometheus_exporter.app.wsgi:application
-
-
-Contributing
-------------
-
-* Pull requests: `Gerrit
- `_
- (see `developer's guide
- `_)
-* Bugs and RFEs: `StoryBoard
- `_
- (please do NOT report bugs to Github)
diff --git a/doc/source/conf.py b/doc/source/conf.py
new file mode 100644
index 0000000..3535503
--- /dev/null
+++ b/doc/source/conf.py
@@ -0,0 +1,74 @@
+# -*- coding: utf-8 -*-
+
+# Copyright 2010-2020 OpenStack Foundation
+#
+# 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
+
+sys.path.insert(0, os.path.abspath('../..'))
+# -- 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'
+]
+
+# 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'
+
+# General information about the project.
+copyright = u'2020, Ironic Developers'
+
+# 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 = 'sphinx'
+
+# -- 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 = 'openstackdocs'
+# html_static_path = ['static']
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'ironic_prometheus_exporter_doc'
+
+latex_use_xindy = False
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass
+# [howto/manual]).
+latex_documents = [
+ ('index',
+ 'doc-ipe.tex',
+ u'Ironic Prometheus Exporter Documentation',
+ u'Ironic Developers', 'manual'),
+]
diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst
new file mode 100644
index 0000000..2787198
--- /dev/null
+++ b/doc/source/configuration.rst
@@ -0,0 +1,74 @@
+Configuration
+=============
+
+To enable the ironic-prometheus-exporter to collect the sensor data from Ironic,
+it's necessary to enable some configuration parameters in the ``ironic.conf``.
+Below you can see an example of the required configuration, the table
+:ref:`ipe_conf` shows all the available configuration options.
+
+
+Example of configuration
+
+.. code-block:: ini
+
+ [conductor]
+ send_sensor_data = true
+ send_sensor_data_interval = 300
+
+ [oslo_messaging_notifications]
+ driver = prometheus_exporter
+ transport_url = fake://
+ location = /opt/stack/node_metrics
+
+
+
+.. _ipe_conf:
+
+.. list-table:: Configuration options for the ironic-prometheus-exporter in Ironic
+ :widths: 15 15 10 50 10
+ :header-rows: 1
+
+ * - Section
+ - Setting
+ - Value
+ - Description
+ - Required
+ * - conductor
+ - send_sensor_data
+ - true
+ - Enable sending sensor data message via the notification bus.
+ - ``Yes``
+ * - conductor
+ - send_sensor_data_interval
+ - 600 (`default`)
+ - Seconds between conductor sending sensor data message via the
+ notification bus.
+ - ``Yes``
+ * - conductor
+ - send_sensor_data_for_undeployed_nodes
+ - false (`default`)
+ - When set to true, the conductor will collect sensor information from
+ all nodes when sensor data collection is enabled via the
+ ``send_sensor_data`` setting.
+ - No
+ * - oslo_messaging_notifications
+ - driver
+ - prometheus_exporter
+ - The Drivers(s) to handle sending notifications.
+ - ``Yes``
+ * - oslo_messaging_notifications
+ - transport_url
+ - fake://
+ - A URL representing the messaging driver to use for notifications.
+ If not set, we fall back to the same configuration used for RPC.
+ - ``Yes``
+ * - oslo_messaging_notifications
+ - location
+ -
+ - Directory where the files will be written.
+ - ``Yes``
+
+
+.. note::
+ After doing the modifications in the ``ironic.conf`` don't forget to re-start
+ the ironic-conductor service
diff --git a/doc/source/index.rst b/doc/source/index.rst
new file mode 100644
index 0000000..cf49dcf
--- /dev/null
+++ b/doc/source/index.rst
@@ -0,0 +1,17 @@
+Welcome to Ironic Prometheus Exporter's documentation!
+======================================================
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Contents:
+
+ install
+ configuration
+ run
+ limitations
+
+Indices and tables
+==================
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/doc/source/install.rst b/doc/source/install.rst
new file mode 100644
index 0000000..9290cc0
--- /dev/null
+++ b/doc/source/install.rst
@@ -0,0 +1,39 @@
+Installation
+============
+
+Pre-Requisites
+--------------
+
+Before installing the exporter you need to have Ironic already installed,
+to know about the limitations check :doc:`limitations`
+
+Supported OS:
+
+* CentOS/RHEL 8
+* Ubuntu Bionic
+
+
+Ironic Prometheus Exporter Installation
+---------------------------------------
+
+The ironic-prometheus-exporter is available as pip package and as rpm package
+on RDO.
+
+#. Package Installation
+
+ #. Using pip::
+
+ $ pip install --user ironic-prometheus-exporter
+
+
+ #. Using rpm from RDO::
+
+ $ dnf install -y python3-ironic-prometheus-exporter
+
+#. Verify the Installation::
+
+ $ pip install entry_point_inspector --user
+ $ epi group show oslo.messaging.notify.drivers
+
+- Output in case of a successful installation: `prometheus_exporter` is listed in the `Name` column and the `Error` column should be empty.
+- Output in case of an unsuccessful installation: `prometheus_exporter` is listed in the `Name` column and the `Error` column will have more information.
diff --git a/doc/source/limitations.rst b/doc/source/limitations.rst
new file mode 100644
index 0000000..b660335
--- /dev/null
+++ b/doc/source/limitations.rst
@@ -0,0 +1,9 @@
+Limitations
+===========
+
+* The only hardware types that have support for sensor data are `ipmi` and
+ `redfish` (If a new hardware type adds support we need to add a parser for
+ it).
+* We can only deal with `Gauge metrics
+ `_.
+* The set of metrics that will be available depends on the hardware type.
diff --git a/doc/source/run.rst b/doc/source/run.rst
new file mode 100644
index 0000000..3ebcb44
--- /dev/null
+++ b/doc/source/run.rst
@@ -0,0 +1,55 @@
+Running the exporter Application
+================================
+
+The exporter application is a Flask Application responsible to merge
+all the metrics files present in the directory set in
+``[oslo_messaging_notifications]/location``.
+
+The prometheus community defined the port of the Ironic Prometheus Exporter
+application as ``9608`` (see `Default port allocations
+`_),
+but you can choose any port for your deployment.
+
+The application needs to have access to the ``ironic.conf``, you need to set
+the ``IRONIC_CONFIG`` environment variable to the absolute path of the file.
+
+We will explain how you can run the application in a development environment
+and in production environment.
+
+Development Environment
+-----------------------
+
+To run the Flask Application follow the steps listed below:
+
+#. Set the ``FLASK_*`` environment variables and the location of the
+ ``ironic.conf`` file.::
+
+ $ export IRONIC_CONFIG=/etc/ironic/ironic.conf
+ $ export FLASK_APP=ironic_prometheus_exporter/app/exporter.py
+ $ export FLASK_RUN_HOST=
+ $ export FLASK_RUN_PORT=9608
+
+#. Run the Flask Application::
+
+ $ python -m flask run
+
+Production Environment
+----------------------
+
+To deploy the application in production you can use any application server, we
+will be using `gunicorn `_ since it's what we use
+in our CI.
+
+The command to execute the application using gunicorn is:
+::
+
+ $ gunicorn3 -b :9608 \
+ --env IRONIC_CONFIG=$IRONIC_CONFIG \
+ --env FLASK_DEBUG=1 -w 4 \
+ --access-logfile=ipe_access.log \
+ --error-logfile=ipe_errors.log \
+ -D ironic_prometheus_exporter.app.wsgi:application
+
+You can find more information about how to deploy a Flask application in
+production in the `Flask documentation
+`_.
diff --git a/tox.ini b/tox.ini
index 30daf61..33d3673 100644
--- a/tox.ini
+++ b/tox.ini
@@ -30,6 +30,20 @@ deps =
commands =
sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
+[testenv:docs]
+deps =
+ -c{env:UPPER_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master}
+ -r{toxinidir}/requirements.txt
+ -r{toxinidir}/doc/requirements.txt
+commands = sphinx-build -W -b html doc/source doc/build/html
+
+[testenv:pdf-docs]
+deps = {[testenv:docs]deps}
+whitelist_externals = make
+commands =
+ sphinx-build -W -b latex doc/source doc/build/pdf
+ make -C doc/build/pdf
+
[testenv:venv]
basepython = python3
setenv = PYTHONHASHSEED=0