From c9ea8ea4a18689e3a86d60ee0fd375ecda6e7ded Mon Sep 17 00:00:00 2001 From: csatari Date: Mon, 26 Jun 2017 14:03:06 +0200 Subject: [PATCH] Aligning install guide with the Pike doc structure In Pike OpenStack documentation is changed in a way that the project repos contain most of the documentation material [1]. This affcects how the doc folder shall be strucutred inside the project repo. With this change I align the install guide to the new structure and correct the warnings during the document generation. The overall work is tracked in [2]. [1]: http://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html [2]: https://etherpad.openstack.org/p/doc-migration-tracking Change-Id: Ib5400247d2ba5f8dac80ef68a43d06868bd42f1c Depends-On: Ia750cb049c0f53a234ea70ce1f2bbbb7a2aa9454 Signed-off-by: csatari --- doc/source/conf.py | 12 +- doc/source/index.rst | 10 +- .../source/install}/get_started.rst | 0 .../source => doc/source/install}/index.rst | 0 .../source/install}/install-rdo.rst | 0 .../source => doc/source/install}/install.rst | 0 .../source/install}/next-steps.rst | 0 .../source => doc/source/install}/verify.rst | 0 doc/source/installation-and-configuration.rst | 42 ++- doc/source/nagios-devstack-installation.rst | 2 +- doc/source/not_operator_support.rst | 30 +- doc/source/notifier-aodh-plugin.rst | 94 ------ doc/source/static-config.rst | 2 +- .../template_validation_status_code.rst | 2 +- doc/source/vitrage-manual-installation.rst | 172 ---------- doc/source/vitrage-template-format.rst | 14 +- install-guide/source/common_configure.rst | 10 - install-guide/source/conf.py | 301 ------------------ setup.cfg | 2 +- test-requirements.txt | 2 +- tox.ini | 3 - 21 files changed, 70 insertions(+), 628 deletions(-) rename {install-guide/source => doc/source/install}/get_started.rst (100%) rename {install-guide/source => doc/source/install}/index.rst (100%) rename {install-guide/source => doc/source/install}/install-rdo.rst (100%) rename {install-guide/source => doc/source/install}/install.rst (100%) rename {install-guide/source => doc/source/install}/next-steps.rst (100%) rename {install-guide/source => doc/source/install}/verify.rst (100%) delete mode 100644 doc/source/notifier-aodh-plugin.rst delete mode 100644 doc/source/vitrage-manual-installation.rst delete mode 100644 install-guide/source/common_configure.rst delete mode 100644 install-guide/source/conf.py diff --git a/doc/source/conf.py b/doc/source/conf.py index 35cdaee29..89fb0141d 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -23,7 +23,7 @@ sys.path.insert(0, os.path.abspath('../..')) extensions = [ 'sphinx.ext.autodoc', # 'sphinx.ext.intersphinx', - 'oslosphinx' + 'openstackdocstheme' ] # autodoc generation is a bit aggressive and a nuisance when doing heavy @@ -38,7 +38,7 @@ master_doc = 'index' # General information about the project. project = u'vitrage' -copyright = u'2016, OpenStack Foundation' +copyright = u'2017, OpenStack Foundation' # If true, '()' will be appended to :func: etc. cross-reference text. add_function_parentheses = True @@ -57,6 +57,14 @@ pygments_style = 'sphinx' # html_theme_path = ["."] # html_theme = '_theme' # html_static_path = ['static'] +html_theme = 'openstackdocs' + +# openstackdocstheme options +repository_name = 'openstack/vitrage' +bug_project = 'vitrage' +bug_tag = 'vitrage' + +html_last_updated_fmt = '%Y-%m-%d %H:%M' # Output file base name for HTML help builder. htmlhelp_basename = '%sdoc' % project diff --git a/doc/source/index.rst b/doc/source/index.rst index 9e27940a5..49577f493 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -52,6 +52,13 @@ or set a deduced state. and states. Currently Vitrage has an Aodh notifier for raising Vitrage alarms in Aodh, and a Nova notifier for marking that the host is down. +Installation Guide +------------------ +.. toctree:: + :maxdepth: 1 + + install/index + Developer Guide --------------- @@ -74,4 +81,5 @@ Design Documents vitrage-use-cases add-new-datasource not_operator_support - template-loading + templates-loading + vitrage-ha-and-history-vision diff --git a/install-guide/source/get_started.rst b/doc/source/install/get_started.rst similarity index 100% rename from install-guide/source/get_started.rst rename to doc/source/install/get_started.rst diff --git a/install-guide/source/index.rst b/doc/source/install/index.rst similarity index 100% rename from install-guide/source/index.rst rename to doc/source/install/index.rst diff --git a/install-guide/source/install-rdo.rst b/doc/source/install/install-rdo.rst similarity index 100% rename from install-guide/source/install-rdo.rst rename to doc/source/install/install-rdo.rst diff --git a/install-guide/source/install.rst b/doc/source/install/install.rst similarity index 100% rename from install-guide/source/install.rst rename to doc/source/install/install.rst diff --git a/install-guide/source/next-steps.rst b/doc/source/install/next-steps.rst similarity index 100% rename from install-guide/source/next-steps.rst rename to doc/source/install/next-steps.rst diff --git a/install-guide/source/verify.rst b/doc/source/install/verify.rst similarity index 100% rename from install-guide/source/verify.rst rename to doc/source/install/verify.rst diff --git a/doc/source/installation-and-configuration.rst b/doc/source/installation-and-configuration.rst index 6bd83531c..e11ee13b8 100644 --- a/doc/source/installation-and-configuration.rst +++ b/doc/source/installation-and-configuration.rst @@ -1,6 +1,6 @@ -============ -Installation -============ +============================== +Installation and configuration +============================== Vitrage Installation ==================== @@ -18,36 +18,32 @@ Enable Vitrage in Devstack --------------------------------------------------- Manual Installation of Vitrage (not using Devstack) --------------------------------------------------- +.. toctree:: + :maxdepth: 1 -* `Vitrage manual installation `_ - -* `Vitrage-dashboard manual installation `_ - + install/index External Monitor Installation ============================= To install Nagios or Zabbix external monitors: -* `Nagios devstack installation `_ - -* `Zabbix devstack installation `_ +.. toctree:: + :maxdepth: 1 + nagios-devstack-installation + zabbix_vitrage Configuration ============= -* `Nagios Plugin Configuration `_ - -* `Static Plugin Configuration `_ - -* `Static Physical Plugin Configuration `_ - -* `Resource State Configuration `_ - -* `Alarm Severity Configuration `_ - -* `Zabbix Configuration `_ - -* `SNMP Sender Configuration `_ +.. toctree:: + :maxdepth: 1 + nagios-config + static-config + static-physical-config + resource-state-config + alarm-severity-config + zabbix_vitrage + notifier-snmp-plugin diff --git a/doc/source/nagios-devstack-installation.rst b/doc/source/nagios-devstack-installation.rst index 3e7bf28b2..995e8a150 100644 --- a/doc/source/nagios-devstack-installation.rst +++ b/doc/source/nagios-devstack-installation.rst @@ -15,7 +15,7 @@ other linux flavours. Links for this purpose are added below. Prerequisites ------------- +------------- Install devstack with vitrage before install Nagios via OMD due to this issue_ .. _issue: https://bugs.launchpad.net/vitrage/+bug/1629811 diff --git a/doc/source/not_operator_support.rst b/doc/source/not_operator_support.rst index 7aaea2533..1f3a11f1e 100644 --- a/doc/source/not_operator_support.rst +++ b/doc/source/not_operator_support.rst @@ -160,20 +160,22 @@ The Switch is attached to a Host that contains a Vm. The Switch is also comprised to a Network which has a Port. There is no edge between the Vm and the Port. - +---------+ +---------+ - +----------- | Host | --------> | Vm | - | +---------+ +---------+ - | - v | -+----------+ N -| Switch | | o -+----------+ t - | - | v - | - | +---------+ +---------+ - +----------> | Network | <--------- | Port | - +---------+ +---------+ +:: + + +---------+ +---------+ + +----------- | Host | --------> | Vm | + | +---------+ +---------+ + | | + v | + +----------+ | N + | Switch | | o + +----------+ | t + | | + | | + | v + | +---------+ +---------+ + +----------> | Network | <-------- | Port | + +---------+ +---------+ :: diff --git a/doc/source/notifier-aodh-plugin.rst b/doc/source/notifier-aodh-plugin.rst deleted file mode 100644 index 0aeadaa33..000000000 --- a/doc/source/notifier-aodh-plugin.rst +++ /dev/null @@ -1,94 +0,0 @@ -=============================== -Vitrage Notifier plugins - AODH -=============================== - -Overview -======== -The Evaluator performs root cause analysis on the Vitrage Graph and may determine that an alarm should be created, deleted or otherwise updated. - -Other components are notified of such changes by the Vitrage Notifier service. Among others, Vitrage Notifier is responsible for handling Aodh Alarms. - -This document describes the implementation of Vitrage Notifier infrastructure and specifically notifying Aodh on Vitrage alarms. - -Design -====== - -:: - - +----------+ +-----------+ +------+ +--------+ - | Vitrage | | DataSource| |Graph | | Message| +------------------+ - | Evaluator|->| Queue |-->| |-------->| Bus |------>| Vitrage Notifier | - +----------+ +-----------+ +------+ | | +------------------+ - | | | | | - | | +----------+ | | - | | | Aodh |---+ | - | | | notifier | |----+ - | | +--| plugin | | | - | | | +----------+ | | - +--------+ | +-----------+ | - | +------------+ - +------------------+ | - | Aodh |<----------------------+ - +------------------+ - -... - -DeducedAlarmNotifier class will be subscribed to entity graph notifications. Whenever a vitrage deduced alarm is added to the graph it will post a message to the message bus. -The processor will hold an instance of the DeducedAlarmNotifier class and will subscribe this instance to entity graph notifications. - -The VitrageNotifier is a new service that listens to the bus for internal vitrage notifications, then can call all the relevant notifier plugins. - -1. Deduced Alarm created by the Evaluator -2. Graph vertex added/updated -3. DeducedAlarmNotifier writes to message bus -4. VitrageNotifierService receives the event and calls all plugins -5. Aodh plugin - using the ceilometer client, creates an event in aodh (with some metadata params in the query) - -Deduced Alarms bus notifications --------------------------------- - -Vitrage Evaluator will create a deduced alarm, sending it to the data source queue -Vitrage Evaluator will use the **vitrage.graph** message bus topic, and will post messages as follows: - - - message of type ``vitrage.deduced_alarm.activate`` : - - * ``name`` - is the alarm name in vitrage - * ``severity`` - is the alarm severity - * ``affected_resource_id`` - is the openstack id of the resource on which the alarm was raised - - - ``vitrage.deduced_alarm.deactivate`` - - * ``id`` - is the alarm id - -Notifier -======== - - Is a new running service - - Receives notifications from the message bus - - Holds instances of all the plugins - - Upon a received notification, calls 'notify(msg)' for all the plugins - - Each plugin is responsible of how and whether to process the notification - -Aodh Plugin -=========== -Vitrage alarms should be reflected as possible in Aodh. The aodh plugin has ceilometer client by which it can send rest calls to aodh - -Handle ``vitrage.deduced_alarm.activate`` ------------------------------------------ -Create an event alarm with the specified severity, where the alarm name is ``vitrage_alarm_name+resource_id`` so to be unique - - - Message does not contain aodh alarm id: - - * plugin will **create** a new aodh alarm - * alarm type - event - * alarm status - alarm - * query contain resource_id, vitrage_id fields - - - Message contains aodh alarm id - - * plugin will **update** the aodh alarm status to alarm - -Handle ``vitrage.deduced_alarm.deactivate`` -------------------------------------------- -Delete an event alarm with the specified id - - * message will contain the aodh alarm id - plugin will **update** the alarm status to ok diff --git a/doc/source/static-config.rst b/doc/source/static-config.rst index d92b6d129..d3c75e68a 100644 --- a/doc/source/static-config.rst +++ b/doc/source/static-config.rst @@ -42,7 +42,7 @@ Static datasource use the same semantics as Vitrage template, except for the fol - All entities configured in static datasource are considered ``RESOURCE`` - ``scenarios`` section is not applicable -There may be more than one configuration file. All files will be read from``/etc/vitrage/static_datasources/``. See +There may be more than one configuration file. All files will be read from ``/etc/vitrage/static_datasources/``. See previous section on how to configure this location. Notes: diff --git a/doc/source/template_validation_status_code.rst b/doc/source/template_validation_status_code.rst index 0d405430f..3894baf09 100644 --- a/doc/source/template_validation_status_code.rst +++ b/doc/source/template_validation_status_code.rst @@ -67,7 +67,7 @@ The following describes all the possible status code and their messages: | 104 | Relationship definition must contain template_id field | syntax | +------------------+---------------------------------------------------------+-------------------------------+ | 120 | Invalid action type. Action type must be from types: | content | - | [action_types] | | +| | [action_types] | | +------------------+---------------------------------------------------------+-------------------------------+ | 121 | At least one action must be defined | syntax | +------------------+---------------------------------------------------------+-------------------------------+ diff --git a/doc/source/vitrage-manual-installation.rst b/doc/source/vitrage-manual-installation.rst deleted file mode 100644 index c61efc0cb..000000000 --- a/doc/source/vitrage-manual-installation.rst +++ /dev/null @@ -1,172 +0,0 @@ -=========================== -Vitrage Manual Installation -=========================== - -Install Vitrage -=============== - -Install vitrage and python-vitrageclient ----------------------------------------- - -To install the Ocata release: - -.. code:: bash - - sudo pip install vitrage==1.5.1 - sudo pip install python-vitrageclient==1.1.1 - - -Or, to install the latest version: - -.. code:: bash - - sudo pip install vitrage - sudo pip install python-vitrageclient - - -Configure Vitrage -================= - -Create the Vitrage folders --------------------------- - -Create /etc/vitrage folder and sub folders, **with permission 755** - -.. code:: bash - - mkdir /etc/vitrage - chmod 755 /etc/vitrage - - mkdir /etc/vitrage/static_datasources - chmod 755 /etc/vitrage/static_datasources - - mkdir /etc/vitrage/templates - chmod 755 /etc/vitrage/templates - - sudo mkdir /var/log/vitrage - sudo chmod 755 /var/log/vitrage - -Copy `policy.json`_ to /etc/vitrage/ - -Copy `api-paste.ini`_ to /etc/vitrage/ - -Copy the `datasources_values`_ folder with its content - -**Note:** You don't need to copy all files in this folder, only the ones that -belong to datasources you plan to use. The only file that **must** be copied -is vitrage.yaml - -.. _policy.json: ../../etc/vitrage/policy.json -.. _api-paste.ini: ../../etc/vitrage/api-paste.ini -.. _datasources_values: ../../etc/vitrage/datasources_values - -Create the vitrage.conf file ----------------------------- - -Create /etc/vitrage/vitrage.conf file with the following information: - -.. code:: bash - - [DEFAULT] - # debug = False - transport_url = - # notifiers = nova - - [service_credentials] - auth_url = http://:5000 - region_name = RegionOne - project_name = admin - password = - project_domain_id = default - user_domain_id = default - username = admin - auth_type = password - - [keystone_authtoken] - auth_uri = http://:5000 - project_domain_name = Default - project_name = service - user_domain_name = Default - password = - username = vitrage - auth_url = http://:35357 - auth_type = password - - -Set the list of datasource you would like to use for Vitrage. -**Note:** In order for a datasource to be supported, the underlying component -(like Neutron, Heat, Zabbix, etc.) should be installed separately. - -.. code:: bash - - [datasources] - types = nova.host,nova.instance,nova.zone,static,aodh,cinder.volume,neutron.network,neutron.port,heat.stack,doctor - - -Configure notifications from other datasources -============================================== - -Notifications from Aodh ------------------------ -In order to configure notifications from Aodh to Vitrage, set the following in -`/etc/aodh/aodh.conf`: - -.. code:: bash - - [oslo_messaging_notifications] - driver = messagingv2 - topics = notifications,vitrage_notifications - - -Notifications from other OpenStack components ---------------------------------------------- - -In order to configure notifications from OpenStack components (Nova, Cinder, -Neutron, Heat and Aodh) to Vitrage, set the following in their conf files: - -.. code:: bash - - [DEFAULT] - notification_topics = notifications,vitrage_notifications - notification_driver=messagingv2 - - -Initialize Vitrage -================== - -Create the Vitrage account --------------------------- - -.. code:: bash - - openstack user create vitrage --password password --domain=Default - openstack role add admin --user vitrage --project service - openstack role add admin --user vitrage --project admin - -Create the Vitrage endpoint ---------------------------- - -.. code:: bash - - openstack service create rca --name vitrage --description="Root Cause Analysis Service" - openstack endpoint create --region --publicurl http://:8999 --internalurl http://:8999 --adminurl http://:8999 vitrage - - -Start the Vitrage Services -========================== - -Run the following commands: - -.. code:: bash - - vitrage-graph - vitrage-api - vitrage-notifier - - -Install the Vitrage Dashboard -============================= - -Follow vitrage-dashboard_ installation procedure - -.. _vitrage-dashboard: https://github.com/openstack/vitrage-dashboard/tree/master/doc/source/installation.rst diff --git a/doc/source/vitrage-template-format.rst b/doc/source/vitrage-template-format.rst index 184ca4b45..a6a2da3c9 100644 --- a/doc/source/vitrage-template-format.rst +++ b/doc/source/vitrage-template-format.rst @@ -66,6 +66,14 @@ relationships: - X and not (Y or Z) - X and not X +Template validation status codes +-------------------------------- + +.. toctree:: + :maxdepth: 1 + + template_validation_status_code + Examples ======== @@ -346,7 +354,7 @@ Set state of specified entity. This will directly affect the state as seen in vi add_causal_relationship -^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^ Add a causal relationship between alarms. :: @@ -361,9 +369,9 @@ mark_down ^^^^^^^^^ Set an entity marked_down field. This can be used along with nova notifier to call force_down for a host - :: +:: - action: + action: action_type : mark_down action_target: target: host # mandatory. entity (from the definitions section, only host) to be marked as down diff --git a/install-guide/source/common_configure.rst b/install-guide/source/common_configure.rst deleted file mode 100644 index e3cc0cac9..000000000 --- a/install-guide/source/common_configure.rst +++ /dev/null @@ -1,10 +0,0 @@ -2. Edit the ``/etc/vitrage/vitrage.conf`` file and complete the following - actions: - - * In the ``[database]`` section, configure database access: - - .. code-block:: ini - - [database] - ... - connection = mysql+pymysql://vitrage:VITRAGE_DBPASS@controller/vitrage diff --git a/install-guide/source/conf.py b/install-guide/source/conf.py deleted file mode 100644 index 7ac6ae913..000000000 --- a/install-guide/source/conf.py +++ /dev/null @@ -1,301 +0,0 @@ -# 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. - -# 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 os -# import sys - - -import openstackdocstheme - -# 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. -# TODO(ajaeger): enable PDF building, for example add 'rst2pdf.pdfbuilder' -# extensions = - -# Add any paths that contain templates here, relative to this directory. -# templates_path = ['_templates'] - -# The suffix of source filenames. -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'Installation Guide for Root Cause Analysis Service' -bug_tag = u'install-guide' -copyright = u'2016, OpenStack contributors' - -# 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 = '0.1' -# The full version, including alpha/beta/rc tags. -release = '0.1' - -# A few variables have to be set for the log-a-bug feature. -# giturl: The location of conf.py on Git. Must be set manually. -# gitsha: The SHA checksum of the bug description. Automatically extracted -# from git log. -# bug_tag: Tag for categorizing the bug. Must be set manually. -# These variables are passed to the logabug code via html_context. -giturl = u'http://git.openstack.org/cgit/openstack/vitrage/tree/install-guide/source' # noqa -git_cmd = "/usr/bin/git log | head -n1 | cut -f2 -d' '" -gitsha = os.popen(git_cmd).read().strip('\n') -html_context = {"gitsha": gitsha, "bug_tag": bug_tag, - "giturl": giturl, - "bug_project": "vitrage"} - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# 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 = ["common_prerequisites.rst", "common_configure.rst"] - -# 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 - - -# -- 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 = 'openstackdocs' - -# 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 = [openstackdocstheme.get_html_theme_path()] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v 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 = [] - -# 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. -# So that we can enable "log-a-bug" links from each output HTML page, this -# variable must be set to a format that includes year, month, day, hours and -# minutes. -html_last_updated_fmt = '%Y-%m-%d %H:%M' - - -# 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 = False - -# 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 = False - -# 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 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 - -# Output file base name for HTML help builder. -htmlhelp_basename = 'install-guide' - -# If true, publish source files -html_copy_source = False - -# -- 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': '', -} - -# 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 = [ - ('index', 'InstallGuide.tex', u'Install Guide', - u'OpenStack contributors', '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 = [ - ('index', 'installguide', u'Install Guide', - [u'OpenStack contributors'], 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 = [ - ('index', 'InstallGuide', u'Install Guide', - u'OpenStack contributors', 'InstallGuide', - 'This guide shows OpenStack end users how to install ' - 'an OpenStack cloud.', 'Miscellaneous'), -] - -# 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 - -# -- Options for Internationalization output ------------------------------ -locale_dirs = ['locale/'] - -# -- Options for PDF output -------------------------------------------------- - -pdf_documents = [ - ('index', u'InstallGuide', u'Install Guide', - u'OpenStack contributors') -] diff --git a/setup.cfg b/setup.cfg index 12e970c46..24162dc72 100644 --- a/setup.cfg +++ b/setup.cfg @@ -52,7 +52,7 @@ packages = source-dir = doc/source build-dir = doc/build all_files = 1 +warning-is-error = 1 [upload_sphinx] upload-dir = doc/build/html - diff --git a/test-requirements.txt b/test-requirements.txt index 3c042ecf0..c10f44ae5 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -16,7 +16,6 @@ python-subunit>=0.0.18 # Apache-2.0/BSD pyzabbix>=0.7.4 # LGPL sphinx!=1.6.1,>=1.5.1 # BSD oslo.log>=3.22.0 # Apache-2.0 -oslosphinx>=4.7.0 # Apache-2.0 oslotest>=1.10.0 # Apache-2.0 oslo.service>=1.10.0 # Apache-2.0 oslo.config>=4.0.0 # Apache-2.0 @@ -36,3 +35,4 @@ pysnmp>=4.2.3 # BSD # Doc requirements openstackdocstheme>=1.5.0 # Apache-2.0 +oslosphinx>=4.7.0 # Apache-2.0 diff --git a/tox.ini b/tox.ini index d940e4f3e..1754ee124 100644 --- a/tox.ini +++ b/tox.ini @@ -47,6 +47,3 @@ exclude=.venv,.git,.tox,dist,doc,*lib/python*,*egg,build [testenv:releasenotes] commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html - -[testenv:install-guide] -commands = sphinx-build -a -E -W -d install-guide/build/doctrees -b html install-guide/source install-guide/build/html