diff --git a/.github/workflows/stackhpc-pull-request.yml b/.github/workflows/stackhpc-pull-request.yml index da4760a84..0504103d3 100644 --- a/.github/workflows/stackhpc-pull-request.yml +++ b/.github/workflows/stackhpc-pull-request.yml @@ -14,6 +14,8 @@ jobs: python-version: 3.8 - environment: releasenotes python-version: 3.8 + - environment: docs + python-version: 3.8 name: Tox ${{ matrix.environment }} with Python ${{ matrix.python-version }} if: github.repository == 'stackhpc/stackhpc-kayobe-config' steps: diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 000000000..95b160c9c --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,7 @@ +# The order of packages is significant, because pip processes them in the order +# of appearance. Changing the order has an impact on the overall integration +# process, which may cause wedges in the gate later. + +reno>=3.1.0 # Apache-2.0 +sphinx>=2.0.0,!=2.1.0 # BSD +sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 000000000..f7214fed0 --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,93 @@ +# Copyright (c) 2017 StackHPC Ltd. +# +# 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. + +# -*- coding: utf-8 -*- +# 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. + +# -- General configuration ---------------------------------------------------- + +# 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.intersphinx', + 'sphinxcontrib.rsvgconverter', +] + +# autodoc generation is a bit aggressive and a nuisance when doing heavy +# text edit cycles. +# execute "export SPHINX_DEBUG=1" in your terminal to disable + +# The suffix of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'stackhpc-kayobe-config' + +# 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 + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'native' + +# -- Options for HTML output -------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +# html_theme_path = [] +html_theme = 'default' +# html_static_path = ['static'] + +# Add any paths that contain "extra" files, such as .htaccess or +# robots.txt. +# html_extra_path = ['_extra'] + +html_theme_options = { + # "show_other_versions": True, +} + +# Output file base name for HTML help builder. +htmlhelp_basename = '%sdoc' % project + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass +# [howto/manual]). +# latex_documents = [ +# ('index', +# 'doc-%s.tex' % project, +# '%s Documentation' % project, +# 'OpenStack Foundation', 'manual'), +# ] + +# Disable usage of xindy https://bugzilla.redhat.com/show_bug.cgi?id=1643664 +latex_use_xindy = False + diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 000000000..24f01975d --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,27 @@ +.. kayobe documentation master file, created by + sphinx-quickstart on Tue Jul 9 22:26:36 2013. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +================================================== +Welcome to StackHPC's Kayobe Config documentation! +================================================== + + +Overview +======== + + + +Contents +======== + + + +Intro +===== + + + +Contributors Guide +================== diff --git a/tox.ini b/tox.ini index 787fe1044..5e1f5a7cb 100644 --- a/tox.ini +++ b/tox.ini @@ -23,3 +23,13 @@ deps = commands = rm -rf releasenotes/build/html sphinx-build -n -W --keep-going -b html releasenotes/source releasenotes/build/html + +[testenv:docs] +allowlist_externals = rm +skip_install = true +deps = + -c{env:TOX_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/xena} + -r{toxinidir}/doc/requirements.txt +commands = + rm -rf doc/build/html + sphinx-build -W --keep-going -b html doc/source doc/build/html \ No newline at end of file