[docs] Update formatting and links

* Fix broken links
* Update display text for links
* Update formatting
* Add hyperlink for barometer

Change-Id: I472a896a51d2fb5a49a4eaac1aef2bdeeed8d692
Signed-off-by: Emma Foley <efoley@redhat.com>

diff --git a/docs/index.rst b/docs/index.rst
index e642491..0ad7d5d 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -35,7 +35,7 @@ support:
 * Detecting and reporting violations that can be consumed by VNFs
   and higher level management systems (through DPDK Keep Alive).
 
 * Detecting and reporting violations that can be consumed by VNFs
   and higher level management systems (through DPDK Keep Alive).
 

-With Barometer the scope is extended to monitoring the NFVI. The ability to
+With `Barometer`_ the scope is extended to monitoring the NFVI. The ability to

 monitor the Network Function Virtualization Infrastructure (NFVI) where VNFs
 are in operation will be a key part of Service Assurance within an NFV
 environment, in order to enforce SLAs or to detect violations, faults or
 monitor the Network Function Virtualization Infrastructure (NFVI) where VNFs
 are in operation will be a key part of Service Assurance within an NFV
 environment, in order to enforce SLAs or to detect violations, faults or


@@ -66,7 +66,6 @@ telemetry such as `collectd`_, and relevant Openstack projects.
      :maxdepth: 3
 
      ./release/configguide/index.rst
      :maxdepth: 3
 
      ./release/configguide/index.rst

-     ./release/scenarios/index.rst

      ./release/userguide/index.rst
      ./release/release-notes/index.rst
      ./development/requirements/index.rst
      ./release/userguide/index.rst
      ./release/release-notes/index.rst
      ./development/requirements/index.rst

diff --git a/docs/release/configguide/index.rst b/docs/release/configguide/index.rst
index 140de49..ecea3db 100644 (file)
--- a/docs/release/configguide/index.rst
+++ b/docs/release/configguide/index.rst
@@ -9,7 +9,7 @@ Anuket Barometer configuration Guide
 ====================================
 
 .. toctree::
 ====================================
 
 .. toctree::

-    :maxdepth: 3
+   :maxdepth: 3

 
    featureconfig
    postinstall
 
    featureconfig
    postinstall

diff --git a/docs/release/userguide/feature.userguide.rst b/docs/release/userguide/feature.userguide.rst
index 6216a3a..c76e79a 100644 (file)
--- a/docs/release/userguide/feature.userguide.rst
+++ b/docs/release/userguide/feature.userguide.rst
@@ -107,7 +107,7 @@ Read Plugins/application: Intel RDT plugin, virt plugin, Open vSwitch stats plug
 Open vSwitch PMD stats application.
 
 Collectd capabilities and usage
 Open vSwitch PMD stats application.
 
 Collectd capabilities and usage

-------------------------------------
+-------------------------------

 .. Describe the specific capabilities and usage for <XYZ> feature.
 .. Provide enough information that a user will be able to operate the feature on a deployed scenario.
 
 .. Describe the specific capabilities and usage for <XYZ> feature.
 .. Provide enough information that a user will be able to operate the feature on a deployed scenario.
 


@@ -149,12 +149,12 @@ Sample configuration files can be found in '/opt/collectd/etc/collectd.conf.d'
   By default, `collectd_exec` user is used in the exec.conf provided in the sample
   configurations directory under src/collectd in the Barometer repo. These scripts *DO NOT* create this user.
   You need to create this user or modify the configuration in the sample configurations directory
   By default, `collectd_exec` user is used in the exec.conf provided in the sample
   configurations directory under src/collectd in the Barometer repo. These scripts *DO NOT* create this user.
   You need to create this user or modify the configuration in the sample configurations directory

-  under src/collectd to use another existing non root user before  running build_base_machine.sh.
+  under src/collectd to use another existing non root user before running build_base_machine.sh.

 
 .. note::
   If you are using any Open vSwitch plugins you need to run:
 
 
 .. note::
   If you are using any Open vSwitch plugins you need to run:
 

-.. code:: bash
+  .. code:: bash

 
     $ sudo ovs-vsctl set-manager ptcp:6640
 
 
     $ sudo ovs-vsctl set-manager ptcp:6640
 


@@ -179,7 +179,7 @@ Repo: https://github.com/collectd/collectd
 
 Branch: main
 
 
 Branch: main
 

-Dependencies: DPDK (https://dpdk.org/)
+Dependencies: `DPDK <https://www.dpdk.org/>`_

 
 .. note:: DPDK statistics plugin requires DPDK version 16.04 or later.
 
 
 .. note:: DPDK statistics plugin requires DPDK version 16.04 or later.
 


@@ -451,7 +451,7 @@ additional two options shown below:
     If you set XDG_CACHE_HOME to anything other than the variable above - you will need to modify
     the path for the EventList configuration.
 
     If you set XDG_CACHE_HOME to anything other than the variable above - you will need to modify
     the path for the EventList configuration.
 

-Use "Cores" option to monitor metrics only for configured cores. If an empty string is provided
+Use ``Cores`` option to monitor metrics only for configured cores. If an empty string is provided

 as value for this field default cores configuration is applied - that is all available cores
 are monitored separately. To limit monitoring to cores 0-7 set the option as shown below:
 
 as value for this field default cores configuration is applied - that is all available cores
 are monitored separately. To limit monitoring to cores 0-7 set the option as shown below:
 


@@ -479,8 +479,8 @@ Branch: main
 
 Dependencies:
 
 
 Dependencies:
 

-  * PQoS/Intel RDT library https://github.com/intel/intel-cmt-cat
-  * msr kernel module
+* PQoS/Intel RDT library https://github.com/intel/intel-cmt-cat
+* msr kernel module

 
 Building and installing PQoS/Intel RDT library:
 
 
 Building and installing PQoS/Intel RDT library:
 


@@ -531,7 +531,7 @@ Repo: https://github.com/collectd/collectd
 
 Branch: feat_ipmi_events, feat_ipmi_analog
 
 
 Branch: feat_ipmi_events, feat_ipmi_analog
 

-Dependencies: OpenIPMI library (http://openipmi.sourceforge.net/)
+Dependencies: `OpenIPMI library <https://openipmi.sourceforge.io/>`_

 
 The IPMI plugin is already implemented in the latest collectd and sensors
 like temperature, voltage, fanspeed, current are already supported there.
 
 The IPMI plugin is already implemented in the latest collectd and sensors
 like temperature, voltage, fanspeed, current are already supported there.


@@ -643,7 +643,7 @@ Repo: https://github.com/collectd/collectd
 
 Branch: main
 
 
 Branch: main
 

-Dependencies: mcelog
+Dependencies: `mcelog <http://mcelog.org/>`_

 
 Start by installing mcelog.
 
 
 Start by installing mcelog.
 


@@ -836,15 +836,15 @@ To inject corrected memory errors:
 * Check the MCE statistic: mcelog --client. Check the mcelog log for injected error details: less /var/log/mcelog.
 
 Open vSwitch Plugins
 * Check the MCE statistic: mcelog --client. Check the mcelog log for injected error details: less /var/log/mcelog.
 
 Open vSwitch Plugins

-^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^

 OvS Plugins Repo: https://github.com/collectd/collectd
 
 OvS Plugins Branch: main
 
 OvS Events MIBs: The SNMP OVS interface link status is provided by standard
 OvS Plugins Repo: https://github.com/collectd/collectd
 
 OvS Plugins Branch: main
 
 OvS Events MIBs: The SNMP OVS interface link status is provided by standard

-IF-MIB (http://www.net-snmp.org/docs/mibs/IF-MIB.txt)
+`IF-MIB <http://www.net-snmp.org/docs/mibs/IF-MIB.txt>`_

 
 

-Dependencies: Open vSwitch, Yet Another JSON Library (https://github.com/lloyd/yajl)
+Dependencies: Open vSwitch, `Yet Another JSON Library <https://github.com/lloyd/yajl>`_

 
 On Centos, install the dependencies and Open vSwitch:
 
 
 On Centos, install the dependencies and Open vSwitch:
 


@@ -915,13 +915,15 @@ For more information on the plugin parameters, please see:
 https://github.com/collectd/collectd/blob/main/src/collectd.conf.pod
 
 OVS PMD stats
 https://github.com/collectd/collectd/blob/main/src/collectd.conf.pod
 
 OVS PMD stats

-^^^^^^^^^^^^^^
-Repo: https://gerrit.opnfv.org/gerrit/barometer
+^^^^^^^^^^^^^
+Repo: https://gerrit.opnfv.org/gerrit/gitweb?p=barometer.git

 
 Prequistes:
 
 Prequistes:

-1. Open vSwitch dependencies are installed.
-2. Open vSwitch service is running.
-3. Ovsdb-server manager is configured.
+
+#. Open vSwitch dependencies are installed.
+#. Open vSwitch service is running.
+#. Ovsdb-server manager is configured.
+

 You can refer `Open vSwitch Plugins`_ section above for each one of them.
 
 OVS PMD stats application is run through the exec plugin.
 You can refer `Open vSwitch Plugins`_ section above for each one of them.
 
 OVS PMD stats application is run through the exec plugin.


@@ -1097,12 +1099,12 @@ http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/
 .. _virt-plugin:
 
 virt plugin
 .. _virt-plugin:
 
 virt plugin

-^^^^^^^^^^^^
+^^^^^^^^^^^

 Repo: https://github.com/collectd/collectd
 
 Branch: main
 
 Repo: https://github.com/collectd/collectd
 
 Branch: main
 

-Dependencies: libvirt (https://libvirt.org/), libxml2
+Dependencies: `libvirt <https://libvirt.org/>`_, libxml2

 
 On Centos, install the dependencies:
 
 
 On Centos, install the dependencies:
 


@@ -1269,7 +1271,7 @@ Reload
     $ sudo systemctl status collectd.service should show success
 
 Additional useful plugins
     $ sudo systemctl status collectd.service should show success
 
 Additional useful plugins

-^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^

 
 **Exec Plugin** : Can be used to show you when notifications are being
 generated by calling a bash script that dumps notifications to file. (handy
 
 **Exec Plugin** : Can be used to show you when notifications are being
 generated by calling a bash script that dumps notifications to file. (handy


@@ -1342,7 +1344,7 @@ For more information on configuring and installing OpenStack plugins for
 collectd, check out the `collectd-openstack-plugins GSG`_.
 
 Security
 collectd, check out the `collectd-openstack-plugins GSG`_.
 
 Security

-^^^^^^^^^
+^^^^^^^^

 * AAA – on top of collectd there secure agents like SNMP V3, Openstack agents
   etc. with their own AAA methods.
 
 * AAA – on top of collectd there secure agents like SNMP V3, Openstack agents
   etc. with their own AAA methods.
 


@@ -1353,7 +1355,7 @@ Security
 
   * Ensuring that only one instance of the program is executed by collectd at any time
   * Forcing the plugin to check that custom programs are never executed with superuser
 
   * Ensuring that only one instance of the program is executed by collectd at any time
   * Forcing the plugin to check that custom programs are never executed with superuser

-  privileges.
+    privileges.

 
 * Protection of Data in flight:
 
 
 * Protection of Data in flight:
 


@@ -1387,8 +1389,8 @@ References
 .. [7] https://collectd.org/wiki/index.php/Meta_Data_Interface
 
 .. _Barometer OPNFV Summit demo: https://prezi.com/kjv6o8ixs6se/software-fastpath-service-quality-metrics-demo/
 .. [7] https://collectd.org/wiki/index.php/Meta_Data_Interface
 
 .. _Barometer OPNFV Summit demo: https://prezi.com/kjv6o8ixs6se/software-fastpath-service-quality-metrics-demo/

-.. _gnocchi plugin: https://github.com/openstack/collectd-openstack-plugins/tree/stable/ocata/
-.. _aodh plugin: https://github.com/openstack/collectd-openstack-plugins/tree/stable/ocata/
+.. _gnocchi plugin: https://opendev.org/x/collectd-openstack-plugins/src/branch/stable/ocata/
+.. _aodh plugin: https://opendev.org/x/collectd-openstack-plugins/src/branch/stable/ocata/

 .. _collectd-openstack-plugins GSG: https://opendev.org/x/collectd-openstack-plugins/src/branch/master/doc/source/GSG.rst
 .. _grafana guide: https://wiki.anuket.io/display/HOME/Installing+and+configuring+InfluxDB+and+Grafana+to+display+metrics+with+collectd 
 .. _CVE-2017-7401: https://www.cvedetails.com/cve/CVE-2017-7401/
 .. _collectd-openstack-plugins GSG: https://opendev.org/x/collectd-openstack-plugins/src/branch/master/doc/source/GSG.rst
 .. _grafana guide: https://wiki.anuket.io/display/HOME/Installing+and+configuring+InfluxDB+and+Grafana+to+display+metrics+with+collectd 
 .. _CVE-2017-7401: https://www.cvedetails.com/cve/CVE-2017-7401/

diff --git a/docs/release/userguide/installguide.docker.rst b/docs/release/userguide/installguide.docker.rst
index ceb0482..20836af 100644 (file)
--- a/docs/release/userguide/installguide.docker.rst
+++ b/docs/release/userguide/installguide.docker.rst
@@ -268,11 +268,12 @@ Collectd-barometer flavors
 
 Before starting to build and run the Collectd container, understand the available
 flavors of Collectd containers:
 
 Before starting to build and run the Collectd container, understand the available
 flavors of Collectd containers:

-  * barometer-collectd - stable release, based on collectd 5.11
-  * barometer-collectd-latest - release based on collectd 'main' branch
-  * barometer-collectd-experimental - release based on collectd 'main'
-    branch that can also include a set of experimental (not yet merged into
-    upstream) pull requests
+
+* barometer-collectd - stable release, based on collectd 5.12
+* barometer-collectd-latest - release based on collectd 'main' branch
+* barometer-collectd-experimental - release based on collectd 'main'
+  branch that can also include a set of experimental (not yet merged into
+  upstream) pull requests

 
 .. note::
    Experimental container is not tested across various OS'es and the stability
 
 .. note::
    Experimental container is not tested across various OS'es and the stability


@@ -302,7 +303,7 @@ are stored in subdirectories of `docker/` directory
 Download the collectd docker image
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 If you wish to use a pre-built barometer image, you can pull the barometer
 Download the collectd docker image
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 If you wish to use a pre-built barometer image, you can pull the barometer

-image from https://hub.docker.com/r/opnfv/barometer-collectd/
+image from `dockerhub <https://hub.docker.com/r/opnfv/barometer-collectd/>`_

 
 .. code:: bash
 
 
 .. code:: bash
 


@@ -403,16 +404,16 @@ The instructions for running the collectd-6 container are the same as for the
 collectd-experimental container.
 
 There are a few useful build args that can be used to further customise the
 collectd-experimental container.
 
 There are a few useful build args that can be used to further customise the

-collectd-6 build::
+collectd-6 build:

 
 

-* COLLECTD_CONFIG_CMD_ARGS
+* **COLLECTD_CONFIG_CMD_ARGS**

   For testing with new plugins for collectd-6, as un-ported plugins are
   disabled by default.
   This new option lets the ./configure command be run with extra args,
   e.g. --enable-cpu --enable-<my-newly-ported-plugin>, which means that
   plugin can be enabled for the PR that is being tested.
 
   For testing with new plugins for collectd-6, as un-ported plugins are
   disabled by default.
   This new option lets the ./configure command be run with extra args,
   e.g. --enable-cpu --enable-<my-newly-ported-plugin>, which means that
   plugin can be enabled for the PR that is being tested.
 

-* COLLECTD_TAG
+* **COLLECTD_TAG**

   This overrides the default tag selected by the flavors, and allows checking
   out out an arbitrary branch (e.g. PR branch instead of using the
   ``COLLECTD_PULL_REQUESTS`` arg, which rebases each PR on top of the
   This overrides the default tag selected by the flavors, and allows checking
   out out an arbitrary branch (e.g. PR branch instead of using the
   ``COLLECTD_PULL_REQUESTS`` arg, which rebases each PR on top of the


@@ -786,8 +787,8 @@ If you wish to use pre-built barometer project's VES and kafka images, you can p
 images from https://hub.docker.com/r/opnfv/barometer-ves/ and  https://hub.docker.com/r/opnfv/barometer-kafka/
 
 .. note::
 images from https://hub.docker.com/r/opnfv/barometer-ves/ and  https://hub.docker.com/r/opnfv/barometer-kafka/
 
 .. note::

-   If your preference is to build images locally please see sections `Build the Kafka Image`_ and
-   `Build VES Image`_
+   If your preference is to build images locally please see sections `Build Kafka Docker Image`_ and
+   `Build VES Docker Image`_

 
 .. code:: bash
 
 
 .. code:: bash
 


@@ -999,7 +1000,7 @@ Run DMA docker image
 ^^^^^^^^^^^^^^^^^^^^
 .. note::
 
 ^^^^^^^^^^^^^^^^^^^^
 .. note::
 

-Run DMA docker image with default configuration
+  Run DMA docker image with default configuration

 
 .. code:: bash
 
 
 .. code:: bash
 

diff --git a/docs/release/userguide/installguide.oneclick.rst b/docs/release/userguide/installguide.oneclick.rst
index 295fdd0..383b53d 100644 (file)
--- a/docs/release/userguide/installguide.oneclick.rst
+++ b/docs/release/userguide/installguide.oneclick.rst
@@ -292,28 +292,34 @@ List of default plugins for collectd container
 .. note::
    From Jerma release, the supported dpdk version is 19.11
 
 .. note::
    From Jerma release, the supported dpdk version is 19.11
 

-   If you would like to use v18.11, Do the following changes:
-    1.Update the dpdk version to v18.11 in <barometer>/src/package-list.mk
-    2.Replace all 'common_linux' string with 'common_linuxapp' in <barometer>/src/dpdk/Makefile
-   
-   If you would like to downgrade to a version lower than v18.11, Do the following changes:
-    1.Update the dpdk version to a version lower than v18.11(Eg:- v16.11) in <barometer>/src/package-list.mk
-    2.Replace all 'common_linux' string with 'common_linuxapp' in <barometer>/src/dpdk/Makefile
-    3.Change the Makefile path from '(WORKDIR)/kernel/linux/kni/Makefile' to (WORKDIR)/lib/librte_eal/linuxapp/kni/Makefile in '(WORK_DIR)/src/dpdk/Makefile'.
+   If you would like to use v18.11, make the following changes:
+
+   1. Update the dpdk version to v18.11 in ``<barometer>/src/package-list.mk``
+   2. Replace all ``common_linux`` string with ``common_linuxapp`` in ``<barometer>/src/dpdk/Makefile``
+
+   If you would like to downgrade to a version lower than v18.11, make the following changes:
+
+   1. Update the dpdk version to a version lower than v18.11 (e.g.:- v16.11) in ``<barometer>/src/package-list.mk``
+   2. Replace all ``common_linux`` string with ``common_linuxapp`` in ``<barometer>/src/dpdk/Makefile``
+   3. Change the Makefile path from ``(WORKDIR)/kernel/linux/kni/Makefile`` to ``(WORKDIR)/lib/librte_eal/linuxapp/kni/Makefile`` in ``(WORK_DIR)/src/dpdk/Makefile``.

 
 By default the collectd is started with default configuration which includes
 the following plugins:
 
 By default the collectd is started with default configuration which includes
 the following plugins:

-    * ``csv``, ``contextswitch``, ``cpu``, ``cpufreq``, ``df``, ``disk``,
-      ``ethstat``, ``ipc``, ``irq``, ``load``, ``memory``, ``numa``,
-      ``processes``, ``swap``, ``turbostat``, ``uuid``, ``uptime``, ``exec``,
-      ``hugepages``, ``intel_pmu``, ``ipmi``, ``write_kafka``, ``logfile``,
-      ``mcelog``, ``network``, ``intel_rdt``, ``rrdtool``, ``snmp_agent``,
-      ``syslog``, ``virt``, ``ovs_stats``, ``ovs_events``, ``dpdk_telemetry``
+
+* ``csv``, ``contextswitch``, ``cpu``, ``cpufreq``, ``df``, ``disk``,
+  ``ethstat``, ``ipc``, ``irq``, ``load``, ``memory``, ``numa``,
+  ``processes``, ``swap``, ``turbostat``, ``uuid``, ``uptime``, ``exec``,
+  ``hugepages``, ``intel_pmu``, ``ipmi``, ``write_kafka``, ``logfile``,
+  ``mcelog``, ``network``, ``intel_rdt``, ``rrdtool``, ``snmp_agent``,
+  ``syslog``, ``virt``, ``ovs_stats``, ``ovs_events``, ``dpdk_telemetry``

 
 .. note::
    Some of the plugins are loaded depending on specific system requirements and can be omitted if
    dependency is not met, this is the case for:
 
 .. note::
    Some of the plugins are loaded depending on specific system requirements and can be omitted if
    dependency is not met, this is the case for:

-   * ``hugepages``, ``ipmi``, ``mcelog``, ``intel_rdt``, ``virt``, ``ovs_stats``, ``ovs_events`` 
+
+   * ``hugepages``, ``ipmi``, ``mcelog``, ``intel_rdt``, ``virt``, ``ovs_stats``, ``ovs_events``
+
+   For instructions on how to disable certain plugins see the `List and description of tags used in ansible scripts`_ section.

 
 .. note::
    The ``dpdkstat`` and ``dpdkevents`` plugins are disabled by default (in
 
 .. note::
    The ``dpdkstat`` and ``dpdkevents`` plugins are disabled by default (in


@@ -322,7 +328,7 @@ the following plugins:
 
    .. code:: bash
 
 
    .. code:: bash
 

-   $ sudo ansible-playbook -i default.inv collectd_service.yml --tags "all,dpdkstats,dpdkevents"
+     $ sudo ansible-playbook -i default.inv collectd_service.yml --tags "all,dpdkstats,dpdkevents"

 
 List and description of tags used in ansible scripts
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 List and description of tags used in ansible scripts
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


@@ -354,7 +360,7 @@ List of available tags:
 ``copy_additional_configs``
   Copy additional configuration files to target system. Path to additional
   configuration is stored in
 ``copy_additional_configs``
   Copy additional configuration files to target system. Path to additional
   configuration is stored in

-  ``$barometer_dir/docker/ansible/roles/config_files/vars/main.yml`` as
+  ``$barometer_dir/docker/ansible/roles/config_files/docs/main.yml`` as

   ``additional_configs_path``.
 
 ``en_default_all``
   ``additional_configs_path``.
 
 ``en_default_all``


@@ -367,7 +373,7 @@ List of available tags:
   ``contextswitch``, ``cpu``, ``cpufreq``, ``df``, ``disk,`` ``ethstat``,
   ``ipc``, ``irq``, ``load``, ``memory``, ``numa``, ``processes``, ``swap``,
   ``turbostat``, ``uptime``, ``exec``, ``hugepages``, ``ipmi``, ``kafka``,
   ``contextswitch``, ``cpu``, ``cpufreq``, ``df``, ``disk,`` ``ethstat``,
   ``ipc``, ``irq``, ``load``, ``memory``, ``numa``, ``processes``, ``swap``,
   ``turbostat``, ``uptime``, ``exec``, ``hugepages``, ``ipmi``, ``kafka``,

-  ``logfile``, ``mcelogs``, ``n``etwork``,`` ``pmu``, ``rdt``, ``rrdtool``,
+  ``logfile``, ``mcelogs``, ``network``, ``pmu``, ``rdt``, ``rrdtool``,

   ``snmp``, ``syslog``, ``virt``, ``ovs_stats``, ``ovs_events``, ``uuid``,
   ``dpdkevents``, ``dpdkstat``, ``dpdk_telemetry``.
 
   ``snmp``, ``syslog``, ``virt``, ``ovs_stats``, ``ovs_events``, ``uuid``,
   ``dpdkevents``, ``dpdkstat``, ``dpdk_telemetry``.