From 06e2f0df246cd423c423e16f2d4dd28c0f33db24 Mon Sep 17 00:00:00 2001 From: Dmitry Ilyin Date: Thu, 11 Feb 2016 23:14:53 +0300 Subject: [PATCH] Add documentation Change-Id: I9bd5372ba41c502ddc76a979c5a30e0c1af9eac1 --- doc/Makefile | 177 +++++++++++++++++++++++++++++++ doc/conf.py | 258 ++++++++++++++++++++++++++++++++++++++++++++++ doc/fixtures.rst | 15 +++ doc/helpers.rst | 13 +++ doc/index.rst | 29 ++++++ doc/make.bat | 242 +++++++++++++++++++++++++++++++++++++++++++ doc/structure.rst | 63 +++++++++++ doc/usage.rst | 258 ++++++++++++++++++++++++++++++++++++++++++++++ doc/utility.rst | 80 ++++++++++++++ requirements.txt | 2 + tox.ini | 19 ++++ 11 files changed, 1156 insertions(+) create mode 100644 doc/Makefile create mode 100644 doc/conf.py create mode 100644 doc/fixtures.rst create mode 100644 doc/helpers.rst create mode 100644 doc/index.rst create mode 100644 doc/make.bat create mode 100644 doc/structure.rst create mode 100644 doc/usage.rst create mode 100644 doc/utility.rst create mode 100644 requirements.txt create mode 100644 tox.ini diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..7cb3dda --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,177 @@ +# 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) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make ' where 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 " 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)" + +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/FuelNoopTests.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/FuelNoopTests.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/FuelNoopTests" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/FuelNoopTests" + @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." + +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." diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..1a6ed19 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,258 @@ +# -*- coding: utf-8 -*- +# +# Fuel Noop Tests documentation build configuration file, created by +# sphinx-quickstart on Thu Feb 11 20:43:50 2016. +# +# 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 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'Fuel Noop Tests' +copyright = u'2016, 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 = '0.1' +# The full version, including alpha/beta/rc tags. +release = '0.1' + +# 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 = ['_build'] + +# 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 = '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 +# " 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 = ['_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 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 = 'FuelNoopTestsdoc' + + +# -- 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', 'FuelNoopTests.tex', u'Fuel Noop Tests Documentation', + u'Mirantis inc', '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', 'fuelnooptests', u'Fuel Noop Tests Documentation', + [u'Mirantis inc'], 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', 'FuelNoopTests', u'Fuel Noop Tests Documentation', + u'Mirantis inc', 'FuelNoopTests', 'One line description of project.', + '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 diff --git a/doc/fixtures.rst b/doc/fixtures.rst new file mode 100644 index 0000000..9fd7163 --- /dev/null +++ b/doc/fixtures.rst @@ -0,0 +1,15 @@ +.. _fuel_noop_fixtures: + +Fuel Noop fixtures +================== + +There is a separate `fuel-noop-fixtures`_ repository to store all of the +fixtures and libraries required for the noop tests execution. +This repository will be automatically fetched before the noop tests are run to +the *tests/noop/fuel-noop-fixtures* directory. + +Developers of the noop tests can add new Hiera and facts yaml files into this +repository instead of the main `fuel-library`_ repository. + +.. _fuel-noop-fixtures: https://github.com/openstack/fuel-noop-fixtures +.. _fuel-library: https://github.com/openstack/fuel-library diff --git a/doc/helpers.rst b/doc/helpers.rst new file mode 100644 index 0000000..29db3a6 --- /dev/null +++ b/doc/helpers.rst @@ -0,0 +1,13 @@ +Using additional RSpec matchers and task helpers +================================================ + +There are some matchers for RSpec one would like to use + +ensure_transitive_dependency(before, after) +------------------------------------------- + +This matcher allows one to check whether there is a +dependency between *after* and *before* resources +even if this dependency is transitional by means +of several other resources or containers such +as classes or defines. diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..f4a4590 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,29 @@ +============================= +Fuel Library Noop Tests Guide +============================= + +Abstract +~~~~~~~~ + +The fuel-library is collection of Puppet modules and related code used by Fuel +to deploy OpenStack environments. There are top-scope Puppet manifests, known +as a Fuel library modular tasks. This guide documents the Fuel Noop testing +framework for these modular tasks. + +Contents +~~~~~~~~ + +.. toctree:: + :maxdepth: 2 + + fixtures + structure + utility + usage + helpers + +Search in this guide +~~~~~~~~~~~~~~~~~~~~ + +* :ref:`search` + diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 0000000..054d5e8 --- /dev/null +++ b/doc/make.bat @@ -0,0 +1,242 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=_build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . +set I18NSPHINXOPTS=%SPHINXOPTS% . +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% + set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :help + echo.Please use `make ^` where ^ 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. 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. text to make text files + echo. man to make manual pages + echo. texinfo to make Texinfo files + echo. gettext to make PO message catalogs + echo. changes to make an overview over 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 + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + + +%SPHINXBUILD% 2> nul +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\FuelNoopTests.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\FuelNoopTests.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdf" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf + cd %BUILDDIR%/.. + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdfja" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf-ja + cd %BUILDDIR%/.. + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The text files are in %BUILDDIR%/text. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "texinfo" ( + %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. + goto end +) + +if "%1" == "gettext" ( + %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The message catalogs are in %BUILDDIR%/locale. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + if errorlevel 1 exit /b 1 + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + if errorlevel 1 exit /b 1 + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + if errorlevel 1 exit /b 1 + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +if "%1" == "xml" ( + %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The XML files are in %BUILDDIR%/xml. + goto end +) + +if "%1" == "pseudoxml" ( + %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. + goto end +) + +:end diff --git a/doc/structure.rst b/doc/structure.rst new file mode 100644 index 0000000..7c0cbf5 --- /dev/null +++ b/doc/structure.rst @@ -0,0 +1,63 @@ +Structure +========= + +Data files +---------- + +To run a noop test on a spec following files are required: + +- A spec file: *(i.e. spec/hosts/my/my_spec.rb)* +- A task file: *(i.e. modular/my/my.pp)* +- One of the Facts sets: *(i.e. ubuntu.yaml)* +- One of the Hiera files: *(i.e. neut_vlan.ceph.controller-ephemeral-ceph.yaml)* + +Any single task is a combination of three attributes: spec file, yaml file +and facts file. Manifest file name and location will be determined automatically +based on the spec file. RSpec framework will try to compile the Puppet catalog +using the manifest file and modules from the module path. It will use the facts +from the facts file and the Hiera data from the hiera file. + +If the spec is empty it will test only that catalog have compiled without any +errors. It's actually not a bad thing because even empty specs can catch most of +basic errors and problems. But if the spec has a **shared_examples 'catalog'** +block defined and there are several examples present they will be run against +the compiled catalog and the matchers will be used to determine if examples +pass or not. + +Every Hiera yaml file also has a corresponding *globals* yaml file that contains +additional processed variables. These files are also used by most of the spec +tests. If you make any changes to the hiera yaml files you should also recreate +globals files by running *globals/globals* specs with *save globals* option +enabled. Later new files can be commited into the fixtures repository. + +And, finally, there is an override system for hiera and facts yaml files. +For each spec file you can create a hiera or facts yaml file with a special +name. This file will be used on top of other files hierarchy. It can be very +useful in cases when you need to provide some custom data which is relevant +only for the one task you are working with without touching any other tasks. + +Framework components +-------------------- + +The Noop test framework consists of the three components: the task manager, +the config and the task. + +The task manager is responsible for collecting the +information about the present files, manipulation the task library, processing +the console options and environment variables and, finally, running the +tasks using the tasks objects and processing reports. + +The config object contains the basic information about directory structure +and some default values and the values passed fro the external environment +variables. This object is static and is persistent between the instances of +all other objects. + +The task object is the instance of a single test run. It can work with spec, +manifest, Hiera and facts yaml paths and run the actual RSpec command to +start the test. + +The similar instance of the task process will be created inside +the RSpec process namespace and will be used to provide the information about +the current task as well as providing many different helpers and features +for the spec users. This object can be accessed through the proxy method of +the root **Noop** object which keep the reference to the current task instance. diff --git a/doc/usage.rst b/doc/usage.rst new file mode 100644 index 0000000..bef68be --- /dev/null +++ b/doc/usage.rst @@ -0,0 +1,258 @@ +Typical use cases +================= + +Let's discuss the most common use cases of the Noop test framework and how it +can be used. + +Running all tests using multiple processes +------------------------------------------ + +Running **tests/noop/noop_tests.sh** without any options will try to execute +all the spec tasks one by one. The list of the spec tasks will be generated by +combining all the possible combinations of specs, hiera files and facts files +that are allowed for this spec. Adding **-p** options allows you to review the +list of tasks that will be run without actually running them. + +Running tasks one by one will be a very time consuming process, so you should +try to use multi-process run instead by providing the **-j** options with a +number of processes that can be started simultaneously. In this mode you +will not see the output of every RSpec process, but you will be able to get +the combined result report of all test runs at the end of the process. + +You can also monitor the progress of tasks by using the debug option **-d**. +It will show you which tasks are starting and finishing and what shell commands +and environment variables are used to run them.:: + + tests/noop/noop_tests.sh -j 24 -d + +Will run all the spec task with debug output and keeping no more then 24 +child processes all the time.:: + + tests/noop/noop_tests.sh -p + +Will output the list of tasks that is going to be run together with the facts +and yaml files used. + +There is also the **run_all.sh** shortcut script for this action. + +Running only a subset of tasks +------------------------------ + +In many cases you would want to run only a subset of tasks, up to only one task. +You can use filters to do so. By providing the **-s**, **-y** and **-f** will +allow you to set one or more specs, yams and facts that you want to use. The +list of tasks will be build by filtering out everything else that you have +not specified. Don't forget that you can use the **-p** option to review the +list of tasks before actually running them. + +List options **-Y**, **-F**, **-S** and **-T** can be used to view the list of +all hiera yaml files, facts files, spec files and task files respectively. +These lists are very helpful for finding out correct values for the filter +options you want to use. Note, that using filter and list options together will +allow you to see the filtered lists.:: + + tests/noop/noop_tests.sh -Y + +Will list all available hiera yaml files.:: + + tests/noop/noop_tests.sh -y neut_vlan.compute.ssl.yaml -p + +Will show you which task are going to run with this yaml file.:: + + tests/noop/noop_tests.sh -y neut_vlan.compute.ssl -s firewall/firewall -f ubuntu + +Will run the *firewall/firewall* spec test with the provided yaml and facts +file, but it will only work if this combination is allowed for this spec. +Note, that you can either provide **.yaml**, **_spec.rb**, **.pp** extensions +for yaml and spec files, or you can omit them and they will be found out on +their own.:: + + tests/noop/noop_tests.sh -y neut_vlan.compute.ssl,neut_vlan.compute.nossl -s firewall/firewall,netconfig/netconfig -p + +Filters can use used with a list of elements like this. + +Recreating globals yaml files +----------------------------- + +All globals files should already be precreated and commited to the fixtures +repository and there is no need for you to create them again in the most cases. +But, if you have made some changes to the existing yaml files or have +added a new one, you should create the globals yamls again. + +You can do it by running *tests/noop/noop_tests.sh* with **-g** option. +It will set filters to run only the globals tasks as well as enabling the +option to save the generated yaml files. Using **-j** option will make the +process much faster. + +There is also the **run_globals.sh** shortcut script for this action. + +Spec file annotations +--------------------- + +The framework builds the list of tasks to run by combining all allowed facts +and yaml files for each spec file and creating a task for every combination. + +By default, the list of yaml files, allowed for each spec will be determined +by the intersection of node roles the spec should be run on (obtained from the +*tasks.yaml* files used by the Nailgun to compile the deployment graph) and the +hiera file roles (obtained from the hiera files themselves). The facts file +will default to **ubuntu** value. + +In most cases it would be better to manually specify the hiera files and, +possibly, the facts files for your spec file, because running a task for every +hiera file with the same roles would be redundant. On the other hand, if you +know which Hiera files can cause a different behaviour of your task, and you +want to test this behaviour in the different scenarios, you can explicitly +specify the list of yaml files and facts files you need. + +The list of Hiera files can be set by using the **HIERA:** commented annotation +string followed by the list of hiera file names separated by the space +character.:: + + # HIERA: neut_vlan.compute.ssl neut_vlan.compute.nossl + +The list of facts files can be specified the same way using the **FACTS:** +annotation.:: + + # FACTS: centos6 centos7 + +The list of task will contain this spec with all possible combinations of the +specified Hiera and facts files. If you need to enter only the precise list of +possible run combinations you can use the **RUN:** annotation.:: + + # RUN: (hiera1) (facts1) + # RUN: (hiera2) (facts2) + +It can be specified many times an all entered combinations will be added to the +list. + +The final annotation **DISABLE_SPEC** allows you to temporarily disable the +spec from being seen the framework. It can use useful if you want to turn off +a spec with run problems and fix them later without breaking the tests.:: + + # DISABLE_SPEC + +The spec file with this annotation will be completely ignored. + +Using hiera and facts overrides +------------------------------- + +In some cases you need a special set of facts values or the Hiera data for +your task. If this values are very specific and are not useful for other tasks +you can use override system instead of creating the new Hiera or facts yaml. + +There are *override* folders inside the Hiera and facts folders. If you place +a yaml file with the specific name to this folder, it will be used during the +spec catalog compilation as the top level of Hiera's hierarchy. The values which +are specified there will be used before the values in other yaml files. Hash +values will be merged on the basic values and the matching key will be +rewritten. Facts yamls work the same way by rewriting the basic values by the +values specified in the override file. + +Both yaml files should be named after the task name with path separator changed +to the dash character. For example, the **firewall/firewall** task will use +the override file name *firewall-firewall.yaml* and +**openstack-controller/keystone** task will use the file name +*openstack-controller-keystone.yaml* if these files are found in the +override folders. + +Working with report files +------------------------- + +When the task manager runs the tasks they leave report files anf the manager +can collect them to generate a combined test report seen at the end of the test +process. These files can be found in the reports folder and re in json format. + +You can use **-r** and **-R** options to load the saved reports from the +previous run and display the report again, or to load reports and run the tasks +that have previously failed after you have tried to somehow fix them. + +The task manager can also generate a test report in *jUnit XML* format using +the **-x** options. It will be saves to the **report.xml** file in the *reports* +folder of the fixtures repository. This file can be used by many tools to +visualize the tests results, notably by the Jenkins CI. + +Catalog debugging +----------------- + +There are several features that can be helpful during writing the initial spec +for a task or when you are debugging a spec failure. Running tasks with **-a** +options will show the report text about which files are being used in this task +run and what files are found in Hiera and facts hierarchies. + +Using **-A** option will output the entire compiled catalog in the Puppet DSL +format. You can review its content and resource parameters to either find +out what resources and classes are there or to see what values the parameters +and properties actually have after all the catalog logic is processed. It's +very helpful when you are debugging a strange task behaviour or writing a spec +file. + +Initial setup options +--------------------- + +The *tests/noop/noop_tests.sh* script will try to do some initial Ruby +environment setup but there are also **-b** and **-B** options to run the +environment setup using *bundle* and to run rspec processes using *bundle exec* +respectively. + +You can also work with the external Puppet modules by using the **-l** and +**-L** options to either install the missing modules or to reset them to the +initial state. + +Using external environment variables and custom paths +----------------------------------------------------- + +There are a number of environment variables used by either the task manager or +by the specs themselves which can alter their behaviour and override the +default or calculated values. + +Paths related: + +- **SPEC_ROOT_DIR** Set the path to the root folder of the framework. Many + other folders are found relative to this path. +- **SPEC_SPEC_DIR** The path to the folder with the spec files. You can change + it but it should be at the *spec/hosts* from the root folder or the + rpsec-puppet will break. +- **SPEC_MODULE_PATH** or **SPEC_MODULEPATH** Set the path to the modules + library. +- **SPEC_TASK_DIR** Set the path to the task manifests folder. +- **SPEC_DEPLOYMENT_DIR** Set the path to the *deployment* directory. It's + actually use only to find the scripts to udate and reset modules. +- **WORKSPACE** This variable is passed by the Jenkins jobs or will default to + the *workspece* folder. Currently used only to store the Ruby gems installed + by the *bundler* if *RVM* is not used. +- **SPEC_FACTS_DIR** The path to the folder with facts yaml files. +- **SPEC_HIERA_DIR** or **SPEC_YAML_DIR** The path to the folder with Hiera + yaml files. + +Spec related: + +- **SPEC_FACTS_NAME** Set the name of the facts file that will be used by the + spec process. + It's set when the task is being run. +- **SPEC_HIERA_NAME** or **SPEC_ASTUTE_FILE_NAME** Set the name of the Hiera + yaml file that will be used by the spec process. + It's set when the task is being run. +- **SPEC_FILE_NAME** Set the spec/manifest file name for the spec process to + test. + It's set when the task is being run and even can override the internal value. +- **SPEC_BUNDLE_EXEC** Use *bundle exec* to run the *rspec* command by the + task object. +- **SPEC_UPDATE_GLOBALS** Save the generated globals files instead of just + checking that globals task's catalog is compiling without and error. +- **SPEC_CATALOG_SHOW** Ask the spec to output the catalog contents. +- **SPEC_SHOW_STATUS** Ask the spec to output the status text. + +Debug related: + +- **SPEC_TASK_CONSOLE** Run the pry console in the manager process. +- **SPEC_RSPEC_CONSOLE** Run the pry console in the RSpec process. +- **SPEC_PUPPET_DEBUG** Enable debug output of the Puppet's catalog compilation. + This variable is also used by many other rspec suites of the Mirantis + Puppet modules outside of the Noop tests framework to output the + additional debug information. +- **SPEC_TASK_DEBUG** Enable the debug output of the task and manager objects. +- **SPEC_DEBUG_LOG** This variable can the the debug log destination file. + +Many of this variables can be set by the Noop manager CLI options, or you can +always export them externally. diff --git a/doc/utility.rst b/doc/utility.rst new file mode 100644 index 0000000..9e1f02a --- /dev/null +++ b/doc/utility.rst @@ -0,0 +1,80 @@ +Using the noop_tests utility +============================ + +The noop_tests options +---------------------- + +Noop tests framework is actually located in the fixtures repository together +with its yaml data files. There is a wrapper script *tests/noop/noop_tests.sh* +that can be used from the Fuel library repository to automatically setup the +external fixtures repository, configure paths and run the framework. + +First, you can use the **-h** options to get the help output.:: + + tests/noop/noop_tests.sh -h + +Output::: + + Usage: noop_tests [options] + Main options: + -j, --jobs JOBS Parallel run RSpec jobs + -g, --globals Run all globals tasks and update saved globals YAML files + -b, --bundle_setup Setup Ruby environment using Bundle + -B, --bundle_exec Use "bundle exec" to run rspec + -l, --update-librarian Run librarian-puppet update in the deployment directory prior to testing + -L, --reset-librarian Reset puppet modules to librarian versions in the deployment directory prior to testing + -o, --report_only_failed Show only failed tasks and examples in the report + -r, --load_saved_reports Read saved report JSON files from the previous run and show tasks report + -R, --run_failed_tasks Run the task that have previously failed again + -M, --list_missing List all task manifests without a spec file + -x, --xunit_report Save report in xUnit format to a file + List options: + -Y, --list_hiera List all hiera yaml files + -S, --list_specs List all task spec files + -F, --list_facts List all facts yaml files + -T, --list_tasks List all task manifest files + Filter options: + -s, --specs SPEC1,SPEC2 Run only these spec files. Example: "hosts/hosts_spec.rb,apache/apache_spec.rb" + -y, --yamls YAML1,YAML2 Run only these hiera yamls. Example: "controller.yaml,compute.yaml" + -f, --facts FACTS1,FACTS2 Run only these facts yamls. Example: "ubuntu.yaml,centos.yaml" + Debug options: + -c, --task_console Run PRY console + -C, --rspec_console Run PRY console in the + -d, --task_debug Show framework debug messages + -D, --puppet_debug Show Puppet debug messages + --debug_log FILE Write all debug messages to this files + -t, --self-check Perform self-check and diagnostic procedures + -p, --pretend Show which tasks will be run without actually running them + Path options: + --dir_root DIR Path to the test root folder + --dir_deployment DIR Path to the test deployment folder + --dir_hiera_yamls DIR Path to the folder with hiera files + --dir_facts_yamls DIR Path to the folder with facts yaml files + --dir_spec_files DIR Path to the folder with task spec files (changing this may break puppet-rspec) + --dir_task_files DIR Path to the folder with task manifest files + --dir_puppet_modules DIR Path to the puppet modules + Spec options: + -A, --catalog_show Show catalog content debug output + -a, --spec_status Show spec status blocks + +Shortcut scripts +---------------- + +There are also several shortcut scripts near the *noop_tests.sh* file that +can be used to perform some common actions. + +- **tests/noop/noop_tests.sh** The main wrapper shell script. It downloads the + fixtures repository, sets the correct paths and setups the Ruby gems. It's + used by many other shortcut scripts. +- **utils/jenkins/fuel_noop_tests.sh** The wrapper script used as an entry point + for the automated Jenkins CI jobs. Runs all tests in parallel mode. +- **tests/noop/rub_all.sh** This wrapper will run all tests in parallel mode. +- **tests/noop/rub_global.sh** This wrapper will run all globals tasks and save + the generated globals yaml files. +- **tests/noop/rub_diagnostics.sh** This wrapper will run the noop tests in the + diagnostics mode to check the presence of all folders in the structure and + the numbers of tasks in the library. +- **run_failed_tasks.sh** This wrapper will load the saved reports files from + the previous run and will try to run all the failed tasks again. +- **purge_reports.sh** Removes all report files. +- **purge_globals.sh** Removes all globals files. diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..c577a66 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,2 @@ +sphinx +cloud_sptheme diff --git a/tox.ini b/tox.ini new file mode 100644 index 0000000..ef03b2c --- /dev/null +++ b/tox.ini @@ -0,0 +1,19 @@ +[tox] +envlist = doc +skipsdist = True + +[testenv] +basepython = + doc: python2.7 + +envdir = + doc: {toxworkdir}/2.7 + +changedir = + doc: {toxinidir}/doc/ + +deps = + -r{toxinidir}/requirements.txt + +commands = + doc: sphinx-build -W -b html . {toxinidir}/doc/_build/html