From 0cd5d45706c89d1912586a068806d0518d35c4dc Mon Sep 17 00:00:00 2001 From: Felipe Monteiro Date: Fri, 15 Sep 2017 21:28:27 +0100 Subject: [PATCH] Add sphinx job for auto-generating docs Sphinx can be leveraged to auto-generate docs into feature-rich HTML pages. Docstrings in modules and classes can be easily auto-injected into documentation to produce high-level documentation, yet with accompanying code blocks and necessary docstrings. This commit introduces the tox job for auto-generating docs, as well as the foundational logic and documentation pages (index, HACKING and glossary). While hacking rules are introduced in HACKING.rst, they are not added in this commit; that will be done in a follow-up patchset. Additional documentation will also be included in a series of future patchsets. Change-Id: Iacd0e4542ebf481d66ab19dd43014b8d5bcc9e3f --- HACKING.rst | 67 +++++++++++++ {docs => doc}/design.md | 0 doc/source/HACKING.rst | 4 + doc/source/_static/.placeholder | 0 doc/source/conf.py | 173 ++++++++++++++++++++++++++++++++ doc/source/glossary.rst | 49 +++++++++ doc/source/index.rst | 43 ++++++++ setup.cfg | 10 +- test-requirements.txt | 3 + tox.ini | 8 +- 10 files changed, 353 insertions(+), 4 deletions(-) create mode 100644 HACKING.rst rename {docs => doc}/design.md (100%) create mode 100644 doc/source/HACKING.rst create mode 100644 doc/source/_static/.placeholder create mode 100644 doc/source/conf.py create mode 100644 doc/source/glossary.rst create mode 100644 doc/source/index.rst diff --git a/HACKING.rst b/HACKING.rst new file mode 100644 index 00000000..b351cfc9 --- /dev/null +++ b/HACKING.rst @@ -0,0 +1,67 @@ +Deckhand Style Commandments +=========================== + +- Step 1: Read the OpenStack Style Commandments + http://docs.openstack.org/developer/hacking/ +- Step 2: Read on + +Deckhand Specific Commandments +------------------------------ + +- [D316] Change assertTrue(isinstance(A, B)) by optimal assert like + assertIsInstance(A, B). +- [D317] Change assertEqual(type(A), B) by optimal assert like + assertIsInstance(A, B). +- [D320] Setting CONF.* attributes directly in tests is forbidden. +- [D322] Method's default argument shouldn't be mutable. +- [D324] Ensure that jsonutils.%(fun)s must be used instead of json.%(fun)s +- [D325] str() and unicode() cannot be used on an exception. Remove use or use six.text_type() +- [D334] Change assertTrue/False(A in/not in B, message) to the more specific + assertIn/NotIn(A, B, message) +- [D335] Check for usage of deprecated assertRaisesRegexp +- [D336] Must use a dict comprehension instead of a dict constructor with a sequence of key-value pairs. +- [D338] Change assertEqual(A in B, True), assertEqual(True, A in B), + assertEqual(A in B, False) or assertEqual(False, A in B) to the more specific + assertIn/NotIn(A, B) +- [D339] Check common raise_feature_not_supported() is used for v2.1 HTTPNotImplemented response. +- [D344] Python 3: do not use dict.iteritems. +- [D345] Python 3: do not use dict.iterkeys. +- [D346] Python 3: do not use dict.itervalues. +- [D350] Policy registration should be in the central location ``deckhand/policies/``. +- [D352] LOG.warn is deprecated. Enforce use of LOG.warning. +- [D355] Enforce use of assertTrue/assertFalse +- [D356] Enforce use of assertIs/assertIsNot +- [D357] Use oslo_utils.uuidutils or uuidsentinel(in case of test cases) to + generate UUID instead of uuid4(). +- [D358] Return must always be followed by a space when returning a value. + +Creating Unit Tests +------------------- +For every new feature, unit tests should be created that both test and +(implicitly) document the usage of said feature. If submitting a patch for a +bug that had no unit test, a new passing unit test should be added. If a +submitted bug fix does have a unit test, be sure to add a new one that fails +without the patch and passes with the patch. + +Running Tests +------------- +The testing system is based on a combination of tox and testr. The canonical +approach to running tests is to simply run the command ``tox``. This will +create virtual environments, populate them with dependencies and run all of +the tests that OpenStack CI systems run. Behind the scenes, tox is running +``testr run --parallel``, but is set up such that you can supply any additional +testr arguments that are needed to tox. For example, you can run: +``tox -- --analyze-isolation`` to cause tox to tell testr to add +--analyze-isolation to its argument list. + +Functional testing leverages gabbi and requires docker as a prerequisite to be +run. Functional tests can be executing by running the command +``tox -e functional``. + +Building Docs +------------- +Normal Sphinx docs can be built via the setuptools ``build_sphinx`` command. To +do this via ``tox``, simply run ``tox -e docs``, +which will cause a virtualenv with all of the needed dependencies to be +created and then inside of the virtualenv, the docs will be created and +put into doc/build/html. diff --git a/docs/design.md b/doc/design.md similarity index 100% rename from docs/design.md rename to doc/design.md diff --git a/doc/source/HACKING.rst b/doc/source/HACKING.rst new file mode 100644 index 00000000..1847447d --- /dev/null +++ b/doc/source/HACKING.rst @@ -0,0 +1,4 @@ +======= +Hacking +======= +.. include:: ../../HACKING.rst diff --git a/doc/source/_static/.placeholder b/doc/source/_static/.placeholder new file mode 100644 index 00000000..e69de29b diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 00000000..6dcc1305 --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,173 @@ +# -*- coding: utf-8 -*- +# +# deckhand documentation build configuration file, created by +# sphinx-quickstart on Sat Sep 16 03:40:50 2017. +# +# 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. + +# 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. +# +# import os +# import sys +# 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 = ['sphinx.ext.autodoc'] + +# Add any paths that contain templates here, relative to this directory. +# templates_path = [] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'deckhand' +copyright = u'2017, Deckhand Authors' +author = u'Deckhand Authors' + +# 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 = u'0.1.0' +# The full version, including alpha/beta/rc tags. +release = u'0.1.0' + +# 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 + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +import sphinx_rtd_theme +html_theme = "sphinx_rtd_theme" +html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + +# 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 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'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# This is required for the alabaster theme +# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars +html_sidebars = { + '**': [ + 'about.html', + 'navigation.html', + 'relations.html', # needs 'show_related': True theme option to display + 'searchbox.html', + 'donate.html', + ] +} + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'deckhanddoc' + + +# -- 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', +} + +# 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, 'deckhand.tex', u'deckhand Documentation', + u'Deckhand Authors', 'manual'), +] + + +# -- 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, 'deckhand', u'deckhand Documentation', + [author], 1) +] + + +# -- 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, 'deckhand', u'deckhand Documentation', + author, 'deckhand', 'Document-based configuration storage service.', + 'Miscellaneous'), +] + + + diff --git a/doc/source/glossary.rst b/doc/source/glossary.rst new file mode 100644 index 00000000..a890c466 --- /dev/null +++ b/doc/source/glossary.rst @@ -0,0 +1,49 @@ +======== +Glossary +======== + +B +~ + +.. glossary:: + + barbican + + Code name of the :term:`Key Manager service + `. + + bucket + + Kind of like a Github repository, an ownership class for documents. + +D +~ + +.. glossary:: + + document + + A collection of metadata and data in YAML format. The data document + format is modeled loosely after Kubernetes practices. The top level of + each document is a dictionary with 3 keys: `schema`, `metadata`, and + `data`. + +K +~ + +.. glossary:: + + Key Manager service (barbican) + + The project that produces a secret storage and + generation system capable of providing key management for + services wishing to enable encryption features. + +U +~ + +.. glossary:: + + UCP + + Acronym for the Undercloud Platform. diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 00000000..27aed70d --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,43 @@ +.. + Copyright 2017 AT&T Intellectual Property. + All Rights Reserved. + + 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. + +==================================== +Welcome to Deckhand's documentation! +==================================== + +Deckhand is a document-based configuration storage service built with +auditability and validation in mind. It serves as the back-end storage service +for UCP. + +Deckhand's primary responsibilities include validating and storing YAML +documents that are layered together to produce finalized documents, containing +site configuration data, including sensitive data. Secrets can be stored using +specialized secret storage management services like Barbican and later +substituted into finalized or "rendered" documents. + +The service understands a variety of document formats, the combination of which +describe the manner in which Deckhand renders finalized documents for +consumption by other UCP services. + +.. toctree:: + :maxdepth: 2 + + HACKING + +.. toctree:: + :maxdepth: 1 + + glossary diff --git a/setup.cfg b/setup.cfg index c26996ed..d597ac60 100644 --- a/setup.cfg +++ b/setup.cfg @@ -24,5 +24,11 @@ packages = oslo.config.opts = deckhand.conf = deckhand.conf.opts:list_opts -[pbr] -warnerrors = True +[build_sphinx] +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 44158b11..69b8717a 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -14,3 +14,6 @@ os-testr>=0.8.0 # Apache-2.0 testrepository>=0.0.18 # Apache-2.0/BSD testtools>=1.4.0 # MIT bandit>=1.1.0 # Apache-2.0 +sphinx>=1.6.2 # BSD +gabbi==1.35.1 +sphinx_rtd_theme==0.2.4 diff --git a/tox.ini b/tox.ini index b00a689c..15821242 100644 --- a/tox.ini +++ b/tox.ini @@ -35,7 +35,6 @@ setenv = VIRTUAL_ENV={envdir} LANGUAGE=en_US deps = -r{toxinidir}/requirements.txt -r{toxinidir}/test-requirements.txt - gabbi==1.35.1 commands = find . -type f -name "*.pyc" -delete {toxinidir}/tools/functional-tests.sh '{posargs}' @@ -67,4 +66,9 @@ commands = flake8 {posargs} # [H904] Delay string interpolations at logging calls. enable-extensions = H106,H203,H204,H205,H210,H904 ignore = E121,E122,E123,E124,E125,E126,E127,E128,E129,E131,E251,H405 -exclude = .venv,.git,.tox,dist,*lib/python*,*egg,build,releasenotes +exclude = .venv,.git,.tox,dist,*lib/python*,*egg,build,releasenotes,doc + +[testenv:docs] +commands = + rm -rf doc/build + python setup.py build_sphinx {posargs}