Uniformize docs across supported versions and output formats

Change-Id: I66d8a7664f0c4d78f54039a85a44cf149ba93113
This commit is contained in:
Olivier Bourdon 2016-03-14 15:17:43 +01:00
parent 8686075038
commit d9cd88a235
19 changed files with 833 additions and 139 deletions

View File

@ -2,6 +2,53 @@
Appendix
========
`Zabbix 2.4 documentation - SNMP traps <https://www.zabbix.com/documentation/2.4/manual/config/items/itemtypes/snmptrap>`_
.. _links:
Links
=====
- `Zabbix Official site <http://www.zabbix.com>`_
- `Zabbix 2.4 documentation <https://www.zabbix.com/documentation/2.4/start>`_
- `Zabbix 2.4 documentation - SNMP traps <https://www.zabbix.com/documentation
/2.4/manual/config/items/itemtypes/snmptrap>`_
- `Zabbix 2.4 documentation - Templates <https://www.zabbix.com/documentation
/2.4/manual/config/templates>`_
- `Fuel Plugins CLI guide <https://docs.mirantis.com/openstack/fuel/fuel-7.0
/user-guide.html#fuel-plugins-cli>`_
.. _licenses:
Components licenses
===================
deb packages
------------
rpm packages
------------
==================== =======
Name License
==================== =======
net-snmp BSD
net-snmp-libs BSD
net-snmp-perl BSD
snmptt GPLv2+
perl-Config-IniFiles GPL+
perl-Crypt-DES BSD
perl-Digest-HMAC GPL+
perl-Digest-SHA1 GPL+
perl-IO-stringy GPL+
perl-List-MoreUtils GPL+
perl-Net-SNMP GPL+
==================== =======
puppet modules
--------------
==== ==========
Name License
==== ==========
snmp Apache 2.0
==== ==========
`Zabbix 2.4 documentation - Templates <https://www.zabbix.com/documentation/2.4/manual/config/templates>`_

View File

@ -0,0 +1,11 @@
Release notes / Changelog
=========================
**1.0.1**
* Compatibility with MOS 8.0
**1.0.0**
* This is the first release of the plugin.

View File

@ -1,7 +1,7 @@
# -*- coding: utf-8 -*-
#
# The Zabbix SNMP Trapd plugin for Fuel documentation build configuration file, created by
# sphinx-quickstart on Tue Nov 3 10:53:03 2015.
# The Zabbix SNMP Trap Daemon plugin for Fuel documentation build configuration file, created by
# sphinx-quickstart on Wed Feb 24 17:05:59 2016.
#
# This file is execfile()d with the current directory set to its
# containing dir.
@ -14,7 +14,6 @@
import sys
import os
import shlex
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
@ -29,9 +28,7 @@ import shlex
# 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.todo',
]
extensions = [ ]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@ -48,25 +45,25 @@ source_suffix = '.rst'
master_doc = 'index'
# General information about the project.
project = u'The Zabbix SNMP Trapd plugin for Fuel'
copyright = u'2016, Mirantis'
author = u'Mirantis'
project = u'The Zabbix SNMP Trap Daemon plugin for Fuel'
copyright = u'2016, Mirantis Inc.'
author = u'Mirantis Inc.'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '1.0.1'
version = '1.0'
# The full version, including alpha/beta/rc tags.
release = '1.0.1'
release = '1.0-1.0.1-1'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
@ -76,7 +73,7 @@ language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = []
#exclude_patterns = []
# The reST default role (used for this markup: `text`) to use for all
# documents.
@ -103,14 +100,14 @@ pygments_style = 'sphinx'
#keep_warnings = False
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True
#todo_include_todos = True
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'classic'
html_theme = 'default'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
@ -218,13 +215,16 @@ latex_elements = {
# Latex figure (float) alignment
#'figure_align': 'htbp',
'classoptions': ',openany,oneside',
'babel': '\\usepackage[english]{babel}'
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'TheZabbixSNMPTrapdpluginforFuel.tex', u'The Zabbix SNMP Trapd plugin for Fuel Documentation',
(master_doc, 'TheZabbixSNMPTrapdpluginforFuel-' + version + '.tex', u'The Zabbix SNMP Trap Daemon plugin for Fuel Documentation',
author, 'manual'),
]
@ -254,8 +254,8 @@ latex_documents = [
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'thezabbixsnmptrapdpluginforfuel', u'The Zabbix SNMP Trapd plugin for Fuel Documentation',
[author], 1),
(master_doc, 'thezabbixsnmptrapdpluginforfuel', u'The Zabbix SNMP Trap Daemon plugin for Fuel Documentation',
[author], 1)
]
# If true, show URL addresses after external links.
@ -268,8 +268,8 @@ man_pages = [
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'TheZabbixSNMPTrapdpluginforFuel', u'The Zabbix SNMP Trapd plugin for Fuel Documentation',
author, 'TheZabbixSNMPTrapdpluginforFuel'),
(master_doc, 'TheZabbixSNMPTrapdpluginforFuel', u'The Zabbix SNMP Trap Daemon plugin for Fuel Documentation',
author, 'TheZabbixSNMPTrapdpluginforFuel')
]
# Documents to append as an appendix to all manuals.
@ -283,3 +283,6 @@ texinfo_documents = [
# If true, do not generate a @detailmenu in the "Top" node's menu.
#texinfo_no_detailmenu = False
# Insert footnotes where they are defined instead of at the end.
pdf_inline_footnotes = True

View File

@ -1,6 +1,6 @@
==================================
SNMP trap daemon for Zabbix plugin
==================================
===============================================
Guide to the SNMP trap daemon for Zabbix plugin
===============================================
This plugin extends Zabbix plugin functionality by adding ability to receive
SNMP traps from management network and pass them to Zabbix. For more

View File

@ -2,16 +2,40 @@
User Guide
==========
Important preliminary notes
===========================
- It is highly recommended to do a network verification check prior
to any deployment.
- This plugin version only supports Ubuntu OS type.
- You can also choose any supervisor and/or also change the
networking configuration according to your needs but you can not use
the old legacy networking mode (nova-network) as this is not supported.
- See Zabbix Plugin for Fuel Documentation for additional notes
Known problems
==============
- `#1529643 <https://bugs.launchpad.net/fuel-plugins/+bug/1529643>`_:
Zabbix snmptrapd: Service "snmptt" was restarted after executing of task "upload\_core\_repos"
- `#1538617 <https://bugs.launchpad.net/fuel-plugins/+bug/1538617>`_:
Cross-plugin display restrictions for some plugins prevent Settings tab from opening.
- See Zabbix Plugin for Fuel Documentation for additional problems
Environment configuration
=========================
1. Create an environment. For more information about environment creation, see
.. highlight:: none
#. Create an environment. For more information about environment creation, see
`Mirantis OpenStack User Guide <http://docs.mirantis.com/openstack/fuel
/fuel-7.0/user-guide.html#create-a-new-openstack-environment>`_.
2. Enable and configure Zabbix plugin for Fuel. For instructions, see Zabbix
#. Enable and configure Zabbix plugin for Fuel. For instructions, see Zabbix
Plugin Guide in the `Fuel Plugins Catalog <https://www.mirantis.com
/products/openstack-drivers-and-plugins/fuel-plugins/>`_.
3. Open *Settings* tab of the Fuel web UI and scroll the page down. On the left
#. Open *Settings* tab of the Fuel web UI and scroll the page down. On the left
choose *SNMP trap daemon for Zabbix plugin*, select the plugin checkbox and
set *SNMP community* parameter:
@ -21,7 +45,8 @@ Environment configuration
You could see default value by clicking on the eye icon. It is highly
recommended to change default SNMP community, because it is used to
authorize incoming SNMP traps.
4. Adjust other environment settings to your requirements and deploy the
#. Adjust other environment settings to your requirements and deploy the
environment. For more information, see
`Mirantis OpenStack User Guide <http://docs.mirantis.com/openstack/fuel
/fuel-7.0/user-guide.html#create-a-new-openstack-environment>`_.
@ -31,20 +56,23 @@ Environment validation
After a successful deployment, all Controller Nodes should have the following:
1. snmptrapd daemon running and listening on UDP/162 port on the VIP address
#. snmptrapd daemon running and listening on UDP/162 port on the VIP address
reserved for Zabbix.
2. snmptrapd daemon configured to pass all SNMP traps to snmptt handler.
3. snmptt daemon running which parse SNMP traps and stores them in a log file
#. snmptrapd daemon configured to pass all SNMP traps to snmptt handler.
#. snmptt daemon running which parse SNMP traps and stores them in a log file
in a format accepted by Zabbix.
4. Zabbix SNMPTrapper processes running which reads SNMP traps from the log
#. Zabbix SNMPTrapper processes running which reads SNMP traps from the log
file (only on node on which Zabbix Server is running).
To test if everything is installed and configured properly, follow these steps:
1. Generate a test SNMP trap running following command from any node::
#. Generate a SNMP test trap by running the following command from any node::
[root@node-46 ~]# snmptrap -v 2c -c <SNMP_community> \
<zabbix_VIP_address> "" .1.3.6.1.4.1.8072.2.3.0.1
# snmptrap -v 2c -c <SNMP_community> <mgmt_VIP_address> "" \
.1.3.6.1.4.1.8072.2.3.0.1
where:
@ -55,33 +83,29 @@ To test if everything is installed and configured properly, follow these steps:
.. image:: ../images/settings.png
:width: 100%
*<zabbix_VIP_address>*
*<mgmt_VIP_address>*
If you dont know the address, run the following command on any node::
[root@node-46 ~]# grep -A2 ^zbx_vip_mgmt /etc/astute.yaml
# awk '/zbx_vip_mgmt/ {n=1} n==1 && /ipaddr/ {print;exit}' \
/etc/astute.yaml | sed -e 's/.*: //'
You should get the required VIP in the output::
zbx_vip_mgmt:
network_role: zabbix
ipaddr: 192.168.0.1
192.168.0.3
2. After several seconds of running the snmptrap command you should see a line
#. After several seconds of running the snmptrap command you should see a line
in the Zabbix Server log file similar to this one::
[root@node-45 ~]# grep netSnmpExampleHeartbeatNotification \
/var/log/zabbix/zabbix_server.log
10730:20150611:182933.176 unmatched trap received from [192.168.0.4]:
18:29:27 2015/06/11 .1.3.6.1.4.1.8072.2.3.0.1 Normal "Status Events"
node-46.domain.tld - netSnmpExampleHeartbeatNotification
# grep netSnmpExampleHeartbeatNotification /var/log/zabbix/zabbix_server.log
10730:20150611:182933.176 unmatched trap received from [192.168.0.4]:
18:29:27 2015/06/11 .1.3.6.1.4.1.8072.2.3.0.1 Normal "Status Events"
node-46.domain.tld - netSnmpExampleHeartbeatNotification
This is a proof that test SNMP trap has been received and passed to Zabbix.
It is “unmatched” for Zabbix because there is no configuration for this trap
in Zabbix (this trap is for testing purposes only).
How to use SNMP trap daemon for Zabbix plugin
=============================================
@ -89,37 +113,45 @@ As noted above, with this plugin you can easily create additional plugins to
add monitoring of SNMP traps specific for your hardware. To achieve this,
the following tasks should be done by additional plugin:
1. On all Controller nodes, add SNMP traps to snmptt configuration:
#. On all Controller nodes, add SNMP traps to snmptt configuration:
a. Create configuration file in */etc/snmp/snmptt.conf.d/* directory, for
#. Create configuration file in */etc/snmp/snmptt.conf.d/* directory, for
example *emc.conf*, with SNMP traps defined, for more information, see
`snmptt documentation <http://snmptt.sourceforge.net/docs/snmptt.shtml
#SNMPTT.CONF-Configuration-file-format>`_.
b. Add the file (absolute path) to *snmptt_conf_files* parameter in
*snmptt.ini* file.
c. Reload snmptt service.
2. Create a Zabbix monitoring Template and export it to a file. For more
#. Add the file (absolute path) to *snmptt_conf_files* parameter in
*snmptt.ini* file.
#. Reload snmptt service.
#. Create a Zabbix monitoring Template and export it to a file. For more
information, see `Templates section in the Zabbix documentation <https://
www.zabbix.com/documentation/2.4/manual/config/templates>`_.
3. From Primary Controller node configure Zabbix:
a. Copy created Template file to the Primary Controller node.
b. Import the Template to Zabbix using *plugin_zabbix_configuration_import*
#. From Primary Controller node configure Zabbix:
#. Copy created Template file to the Primary Controller node.
#. Import the Template to Zabbix using *plugin_zabbix_configuration_import*
resource.
c. Optionally, create a Host group in Zabbix using *plugin_zabbix_hostgroup*
#. Optionally, create a Host group in Zabbix using *plugin_zabbix_hostgroup*
resource.
d. Create Host in Zabbix using *plugin_zabbix_host* resource setting
#. Create Host in Zabbix using *plugin_zabbix_host* resource setting
appropriate name, IP and group.
e. Link the Template with the Host using *plugin_zabbix_template_link*
#. Link the Template with the Host using *plugin_zabbix_template_link*
resource.
There are two plugins in the `Fuel Plugins Catalog <https://www.mirantis.com
/products/openstack-drivers-and-plugins/fuel-plugins/>`_ you can refer to as an
example:
1. EMC hardware monitoring extension for Zabbix plugin.
2. Extreme Networks hardware monitoring extension for Zabbix plugin.
#. EMC hardware monitoring extension for Zabbix plugin.
#. Extreme Networks hardware monitoring extension for Zabbix plugin.
These plugins do all the tasks mentioned above and have their own Zabbix
monitoring Templates. You can simply copy one of these plugins and adjust SNMP

View File

@ -1,17 +1,18 @@
***********************************************
Guide to the SNMP trap daemon for Zabbix plugin
***********************************************
This document provides instructions for installing, configuring and using
SNMP trap daemon for Zabbix plugin.
=======================================================================
Welcome to The Zabbix SNMP trap daemon plugin for Fuel's documentation!
=======================================================================
.. toctree::
:maxdepth: 2
:maxdepth: 3
terms.rst
description.rst
installation.rst
guide.rst
appendix.rst
licenses.rst
revisionhistory
purpose
keyterms
description
changelog
limitations
installation
guide
troubleshooting
appendix

View File

@ -7,25 +7,28 @@ SNMP trap daemon for Zabbix plugin installation
To install SNMP trap daemon for Zabbix plugin, follow these steps:
1. Download and install the Zabbix plugin for Fuel from the
.. highlight:: none
#. Download and install the Zabbix plugin for Fuel from the
`Fuel Plugins Catalog <https://www.mirantis.com/products/
openstack-drivers-and-plugins/fuel-plugins/>`_.
2. Download the SNMP trap daemon for Zabbix plugin from the
#. Download the SNMP trap daemon for Zabbix plugin from the
`Fuel Plugins Catalog <https://www.mirantis.com/products/
openstack-drivers-and-plugins/fuel-plugins/>`_.
3. Copy the plugin on already installed Fuel Master node, ssh can be used for
#. Copy the plugin on already installed Fuel Master node, ssh can be used for
that. If you do not have the Fuel Master node yet, see `Quick Start Guide
<https://software.mirantis.com/quick-start/>`_::
# scp zabbix_snmptrapd-1.0-1.0.1-1.noarch.rpm \
root@<The_Fuel_Master_node_IP>:/tmp
# scp zabbix_snmptrapd-1.0-1.0.1-1.noarch.rpm root@<Fuel_Master_IP>:/tmp
4. Log into the Fuel Master node. Install the plugin::
#. Log into the Fuel Master node. Install the plugin::
# cd /tmp
# fuel plugins --install zabbix_snmptrapd-1.0-1.0.1-1.noarch.rpm
5. Check if the plugin was installed successfully::
#. Check if the plugin was installed successfully::
# fuel plugins
id | name | version | package_version
@ -33,3 +36,22 @@ To install SNMP trap daemon for Zabbix plugin, follow these steps:
1 | zabbix_monitoring | 2.5.0 | 3.0.0
2 | zabbix_snmptrapd | 1.0.1 | 2.0.0
SNMP trap daemon for Zabbix plugin removal
==========================================
To uninstall SNMP Trap Daemon for Zabbix plugin, follow these steps:
#. Delete all Environments in which SNMP Trap Daemon for Zabbix plugin has been enabled.
#. Uninstall the plugin::
# fuel plugins --remove zabbix_snmptrapd==1.0.1
#. Check if the plugin was uninstalled successfully::
# fuel plugins
id | name | version | package_version
---|---------------------------|----------|----------------
...
You can still have other plugins listed here but not zabbix_snmptrapd

View File

@ -5,7 +5,7 @@ Key terms, acronyms and abbreviations
Zabbix
An enterprise open source monitoring solution for networks and
applications. It is designed to monitor and track the status of various
network services,servers, and other network hardware.
network services, servers, and other network hardware.
VIP
Virtual IP Address.

View File

@ -1,32 +0,0 @@
===================
Components licenses
===================
rpm packages
============
====================== ============
Name License
====================== ============
net-snmp BSD
net-snmp-libs BSD
net-snmp-perl BSD
snmptt GPLv2+
perl-Config-IniFiles GPL+
perl-Crypt-DES BSD
perl-Digest-HMAC GPL+
perl-Digest-SHA1 GPL+
perl-IO-stringy GPL+
perl-List-MoreUtils GPL+
perl-Net-SNMP GPL+
====================== ============
puppet modules
==============
====================== ==============
Name License
====================== ==============
snmp Apache 2.0
====================== ==============

View File

@ -0,0 +1,5 @@
Limitations
===========
The plugin only supports neutron when specifying network settings. Old legacy mode (nova-network) is not supported

View File

@ -0,0 +1,8 @@
================
Document purpose
================
This document provides instructions for installing, configuring and
using Zabbix SNMP trap daemon extension to the Zabbix monitoring
plugin for Fuel.

View File

@ -0,0 +1,24 @@
================
Revision history
================
======= ============= ============================ =====================
Version Revision date Editor Comment
======= ============= ============================ =====================
0.1 06.19.2015 Piotr Misiak First release
(pmisiak@mirantis.com)
------- ------------- ---------------------------- ---------------------
0.2 08.12.2015 Piotr Misiak Updated release
(pmisiak@mirantis.com)
------- ------------- ---------------------------- ---------------------
0.3 08.02.2015 Marciej Relewicz Updated for fix
(mrelewicz@mirantis.com)
------- ------------- ---------------------------- ---------------------
1.0.0 11.20.2015 Swann Croiset New Major version
(scroiset@mirantis.com)
------- ------------- ---------------------------- ---------------------
1.0.1 03.14.2016 Olivier Bourdon Added MOS 8.0 support
(obourdon@mirantis.com)
Doc fixes
======= ============= ============================ =====================

View File

@ -0,0 +1,83 @@
===============
Troubleshooting
===============
.. highlight:: none
Running processes
=================
After a successfull deployment the following processes should be running on
the controller node which runs the Zabbix server (lines have been wrapped
for more readability)::
root 10222 1 0 13:54 ? 00:00:00
/usr/sbin/snmptrapd -Lsd -p /var/run/snmptrapd.pid
root 10330 1 0 13:54 ? 00:00:00
/usr/bin/perl /usr/sbin/snmptt --daemon
snmptt 10331 10330 0 13:54 ? 00:00:00
/usr/bin/perl /usr/sbin/snmptt --daemon
snmp 19521 1 0 13:49 ? 00:00:00
/usr/sbin/snmpd -Lsd -Lf /dev/null -u snmp -g snmp -I
-smux mteTrigger mteTriggerConf -p /var/run/snmpd.pid
This processes ensure that the SNMP traps can be handled by Zabbix
If some of them do not run, please try to relaunch them appropriately using one of the following commands::
# service snmpd restart
# service snmptt restart
For the snmptrapper process, please make sure the contents of the corresponding
Zabbix configuration file is accurate::
# cat /etc/zabbix/conf.d/zabbix_snmp.conf
### Managed by Puppet ###
# This is SNMP config file for ZABBIX server process
# To get more information about ZABBIX,
# go http://www.zabbix.com
############ GENERAL PARAMETERS #################
#SNMP Trapper
StartSNMPTrapper=1
SNMPTrapperFile=/var/log/snmptt/snmptt.log
and potentially restart the Zabbix server process which is managed by pacemaker.
See Zabbix Plugin for Fuel Documentation to see how to do this.
Finding the management VIP to use to send SNMP traps
====================================================
On the Fuel master node, use the primary controller node (here node-3)::
# ssh -q node-3 ip netns exec haproxy ifconfig b_zbx_vip_mgmt | \
grep 'inet addr:' | sed -e 's/[^:]*://' -e 's/ .*//'
192.168.0.3
Note that there is another way to find this::
# ssh -q node-3 "awk '/zbx_vip_mgmt/ {n=1} n==1 && /ipaddr/ {print;exit}' \
/etc/astute.yaml" | sed -e 's/.*: //'
192.168.0.3
SNMP processes log files
========================
The files can be found under::
/var/log/snmptt/snmpttsystem.log
Zabbix log files
================
On any of the cluster node, you might want to look into the Zabbix
agents and server log files under::
/var/log/zabbix
Additional reading
==================
See Zabbix Plugin for Fuel Documentation for additional troubleshooting tips

View File

@ -1,6 +1,6 @@
# -*- coding: utf-8 -*-
#
# The Zabbix SNMP Trapd plugin for Fuel documentation build configuration file, created by
# The Zabbix SNMP Trapd plugin for Fuel test plan documentation build configuration file, created by
# sphinx-quickstart on Tue Nov 3 10:53:03 2015.
#
# This file is execfile()d with the current directory set to its
@ -14,7 +14,6 @@
import sys
import os
import shlex
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
@ -29,9 +28,7 @@ import shlex
# 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.todo',
]
extensions = [ ]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@ -48,25 +45,25 @@ source_suffix = '.rst'
master_doc = 'index'
# General information about the project.
project = u'The Zabbix SNMP Trapd plugin for Fuel'
copyright = u'2016, Mirantis'
author = u'Mirantis'
project = u'The Zabbix SNMP Trapd plugin for Fuel Test Plan'
copyright = u'2016, Mirantis Inc.'
author = u'Mirantis Inc.'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '1.0.1'
version = '1.0'
# The full version, including alpha/beta/rc tags.
release = '1.0.1'
release = '1.0-1.0.1-1'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
@ -76,7 +73,7 @@ language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = []
#exclude_patterns = []
# The reST default role (used for this markup: `text`) to use for all
# documents.
@ -103,14 +100,14 @@ pygments_style = 'sphinx'
#keep_warnings = False
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True
#todo_include_todos = True
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'classic'
html_theme = 'default'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
@ -202,7 +199,7 @@ html_static_path = ['_static']
#html_search_scorer = 'scorer.js'
# Output file base name for HTML help builder.
htmlhelp_basename = 'TheZabbixSNMPTrapdpluginforFueldoc'
htmlhelp_basename = 'TheZabbixSNMPTrapdpluginforFuelTestPlanDoc'
# -- Options for LaTeX output ---------------------------------------------
@ -218,13 +215,16 @@ latex_elements = {
# Latex figure (float) alignment
#'figure_align': 'htbp',
'classoptions': ',openany,oneside',
'babel': '\\usepackage[english]{babel}'
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'TheZabbixSNMPTrapdpluginforFuel.tex', u'The Zabbix SNMP Trapd plugin for Fuel Documentation',
(master_doc, 'TheZabbixSNMPTrapdpluginforFuelTestPlan-' + version + '.tex', u'The Zabbix SNMP Trapd plugin for Fuel Test Plan Documentation',
author, 'manual'),
]
@ -254,8 +254,8 @@ latex_documents = [
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'thezabbixsnmptrapdpluginforfuel', u'The Zabbix SNMP Trapd plugin for Fuel Documentation',
[author], 1),
(master_doc, 'thezabbixsnmptrapdpluginforfueltestplan', u'The Zabbix SNMP Trapd plugin for Fuel Test Plan Documentation',
[author], 1)
]
# If true, show URL addresses after external links.
@ -268,8 +268,8 @@ man_pages = [
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'TheZabbixSNMPTrapdpluginforFuel', u'The Zabbix SNMP Trapd plugin for Fuel Documentation',
author, 'TheZabbixSNMPTrapdpluginforFuel'),
(master_doc, 'TheZabbixSNMPTrapdpluginforFuelTestPlan', u'The Zabbix SNMP Trapd plugin for Fuel Test Plan Documentation',
author, 'TheZabbixSNMPTrapdpluginforFuelTestPlan')
]
# Documents to append as an appendix to all manuals.
@ -283,3 +283,6 @@ texinfo_documents = [
# If true, do not generate a @detailmenu in the "Top" node's menu.
#texinfo_no_detailmenu = False
# Insert footnotes where they are defined instead of at the end.
pdf_inline_footnotes = True

192
doc/specs/Makefile Normal file
View File

@ -0,0 +1,192 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = build
# User-friendly check for sphinx-build
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
endif
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " applehelp to make an Apple Help Book"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
@echo " coverage to run coverage check of the documentation (if enabled)"
clean:
rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/TheZabbixpluginforFuel.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/TheZabbixpluginforFuel.qhc"
applehelp:
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
@echo
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
@echo "N.B. You won't be able to view it unless you put it in" \
"~/Library/Documentation/Help or install it in your application" \
"bundle."
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/TheZabbixpluginforFuel"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/TheZabbixpluginforFuel"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
latexpdfja:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
coverage:
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
@echo "Testing of coverage in the sources finished, look at the " \
"results in $(BUILDDIR)/coverage/python.txt."
xml:
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
pseudoxml:
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

View File

288
doc/specs/source/conf.py Normal file
View File

@ -0,0 +1,288 @@
# -*- coding: utf-8 -*-
#
# The Zabbix SNMP Trapd plugin for Fuel specification documentation build configuration file, created by
# sphinx-quickstart on Tue Nov 3 10:53:03 2015.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys
import os
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [ ]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'The Zabbix SNMP Trapd plugin for Fuel Specification'
copyright = u'2016, Mirantis Inc.'
author = u'Mirantis Inc.'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '1.0'
# The full version, including alpha/beta/rc tags.
release = '1.0-1.0.1-1'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
#exclude_patterns = []
# The reST default role (used for this markup: `text`) to use for all
# documents.
#default_role = None
# 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
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
#keep_warnings = False
# If true, `todo` and `todoList` produce output, else they produce nothing.
#todo_include_todos = True
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'default'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
#html_search_language = 'en'
# A dictionary with options for the search language support, empty by default.
# Now only 'ja' uses this config value
#html_search_options = {'type': 'default'}
# The name of a javascript file (relative to the configuration directory) that
# implements a search results scorer. If empty, the default will be used.
#html_search_scorer = 'scorer.js'
# Output file base name for HTML help builder.
htmlhelp_basename = 'TheZabbixSNMPTrapdpluginforFuelSpecDoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
# Latex figure (float) alignment
#'figure_align': 'htbp',
'classoptions': ',openany,oneside',
'babel': '\\usepackage[english]{babel}'
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'TheZabbixSNMPTrapdpluginforFuelSpec-' + version + '.tex', u'The Zabbix SNMP Trapd plugin for Fuel Specification Documentation',
author, 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'thezabbixsnmptrapdpluginforfuelspec', u'The Zabbix SNMP Trapd plugin for Fuel Specification Documentation',
[author], 1)
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'TheZabbixSNMPTrapdpluginforFuelSpec', u'The Zabbix SNMP Trapd plugin for Fuel Specification Documentation',
author, 'TheZabbixSNMPTrapdpluginforFuelSpec')
]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
#texinfo_no_detailmenu = False
# Insert footnotes where they are defined instead of at the end.
pdf_inline_footnotes = True

13
tox.ini
View File

@ -1,5 +1,5 @@
[tox]
envlist = manifests,plugin_zabbix_snmptrapd,build_plugin,docs,qa_docs
envlist = manifests,plugin_zabbix_snmptrapd,build_plugin,docs,qa_docs,spec_docs
skipsdist = True
[testenv]
@ -38,14 +38,21 @@ commands =
fpb --check {toxinidir} --debug
fpb --build {toxinidir} --debug
[testenv:spec_docs]
changedir = {toxinidir}/doc/specs
whitelist_externals = make
commands =
make clean html singlehtml SPHINXOPTS=-W
[testenv:docs]
changedir = {toxinidir}/doc/plugin-guide
whitelist_externals = make
commands =
make clean html SPHINXOPTS=-W
make clean html singlehtml SPHINXOPTS=-W
[testenv:qa_docs]
changedir = {toxinidir}/doc/qa
whitelist_externals = make
commands =
make clean html SPHINXOPTS=-W
make clean html singlehtml SPHINXOPTS=-W