Shipyard documentation via build_sphinx

This PS adds tooling and automation to automatically generate
Shipyard's documentation into feature-rich HTML pages that can
be hosted.

To run the documentation job, simply execute:

    tox -e docs

Shipyard's .md documentation will have to be changed to .rst
in a future PS for sphinx to be able to render them into HTML.

Change-Id: Iba8cfd68e4905d49cd5a1dfd39d556044efdabbd
This commit is contained in:
Felipe Monteiro 2017-10-05 18:44:28 +01:00 committed by Tin Lam
parent f1d357d890
commit 467358dcc2
9 changed files with 273 additions and 1 deletions

1
.gitignore vendored
View File

@ -63,6 +63,7 @@ instance/
# Sphinx documentation
docs/_build/
docs/*/_static/
# PyBuilder
target/

View File

170
docs/source/conf.py Normal file
View File

@ -0,0 +1,170 @@
# -*- coding: utf-8 -*-
#
# shipyard 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',
'sphinx.ext.todo',
'sphinx.ext.viewcode',
'oslo_config.sphinxconfiggen',
'oslo_policy.sphinxpolicygen'
]
# oslo_config.sphinxconfiggen options
config_generator_config_file = '../../generator/config-generator.conf'
sample_config_basename = '_static/shipyard'
# oslo_policy.sphinxpolicygen options
policy_generator_config_file = '../../generator/policy-generator.conf'
sample_policy_basename = '_static/shipyard'
# 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'Shipyard'
copyright = u'2017, Shipyard Authors'
author = u'Shipyard 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']
# -- Options for HTMLHelp output ------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'shipyarddoc'
# -- 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, 'shipyard.tex', u'Shipyard Documentation',
u'Shipyard 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, 'Shipyard', u'Shipyard 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, 'Shipyard', u'Shipyard Documentation',
author, 'Shipyard',
'Directed acyclic graph controller for Kubernetes and OpenStack CP life-cycle management.',
'Miscellaneous'),
]

34
docs/source/index.rst Normal file
View File

@ -0,0 +1,34 @@
..
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 Shipyard's documentation!
====================================
Shipyard is a directed acyclic graph controller for Kubernetes and OpenStack
control plane life-cycle management.
User's Guide
============
Shipyard Configuration Guide
----------------------------
.. toctree::
:maxdepth: 2
sampleconf
policy-enforcement

View File

@ -0,0 +1,25 @@
..
Copyright 2017 AT&T Intellectual Property. All other 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.
Sample Policy File
==================
The following is a sample Shipyard policy file for adaptation and use. It is
auto-generated from Shipyard when this documentation is built, so
if you are having issues with an option, please compare your version of
Shipyard with the version of this documentation.
The sample policy file can also be viewed in `file form <_static/shipyard.policy.yaml.sample>`_.
.. literalinclude:: _static/shipyard.policy.yaml.sample

View File

@ -0,0 +1,26 @@
..
Copyright 2017 AT&T Intellectual Property. All other 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.
Sample Configuration File
==========================
The following is a sample Shipyard configuration for adaptation and use. It is
auto-generated from Shipyard when this documentation is built, so
if you are having issues with an option, please compare your version of
Patrole with the version of this documentation.
The sample configuration can also be viewed in `file form <_static/shipyard.conf.sample>`_.
.. literalinclude:: _static/shipyard.conf.sample

View File

@ -25,4 +25,10 @@ oslo.policy.policies =
shipyard_airflow = shipyard_airflow.policy:list_policies
[build_sphinx]
warning-is-error = True
source-dir = docs/source
build-dir = docs/build
all_files = 1
warning-is-error = 1
[upload_sphinx]
upload-dir = docs/build/html

View File

@ -9,3 +9,7 @@ flake8==3.3.0
# Security scanning
bandit>=1.1.0 # Apache-2.0
# Documentation
sphinx>=1.6.2
sphinx_rtd_theme==0.2.4

View File

@ -32,3 +32,9 @@ ignore = F841
# NOTE(Bryan Strassner) excluding 3rd party and generated code that is brought into the
# codebase.
exclude = *plugins/rest_api_plugin.py,*lib/python*,*egg,.git*,*.md,.tox*,alembic/env.py,build/*
[testenv:docs]
whitelist_externals=rm
commands =
rm -rf docs/build
python setup.py build_sphinx {posargs}