From 8ecd19a39553a47706ff92510dffdc6773110785 Mon Sep 17 00:00:00 2001 From: Federico Ressi Date: Wed, 13 Jan 2021 13:45:03 +0100 Subject: [PATCH] Use the ansible openstack project template This also create a new Tox environment for building project documentation Change-Id: I8b958df06caede619213157f4e175ade186fb885 --- .gitignore | 6 ++ doc/Makefile | 19 +++++++ doc/requirements.txt | 9 +++ doc/source/_static/README.txt | 1 + doc/source/conf.py | 104 ++++++++++++++++++++++++++++++++++ doc/source/index.rst | 1 + tox.ini | 11 +++- zuul.d/project.yaml | 5 +- 8 files changed, 151 insertions(+), 5 deletions(-) create mode 100644 doc/Makefile create mode 100644 doc/requirements.txt create mode 100644 doc/source/_static/README.txt create mode 100644 doc/source/conf.py create mode 100644 doc/source/index.rst diff --git a/.gitignore b/.gitignore index d98ab23..7e94d84 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,9 @@ # Tox files .tox + +# Docs files +/doc/build/ +/doc/source/_static/* + +# Vagrant files .vagrant diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..ba501f6 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,19 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 0000000..ae5795d --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,9 @@ +# 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. + +# As openstack job build-reno-releasenotes and Read The Docs page support only +# one single requirements file for a project, we need to have one such file +# which will include all project requirements +sphinx>=3.4.2 # BSD +sphinx_rtd_theme>=0.5.1,<1 # Apache-2.0 diff --git a/doc/source/_static/README.txt b/doc/source/_static/README.txt new file mode 100644 index 0000000..f1591f1 --- /dev/null +++ b/doc/source/_static/README.txt @@ -0,0 +1 @@ +This file is here only to make sure this folder exists on Git repository. diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000..8e34622 --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,104 @@ +# Copyright 2021 Red Hat +# +# 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. + +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# 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 + +BASE_DIR = os.path.dirname(os.path.abspath(__file__)) + + +# -- Project information ----------------------------------------------------- + +project = 'Devstack Plugin Tobiko' +copyright = "2020, Red Hat" +author = "Tobiko's Team" + +release = '' +version = '' + + +# -- 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.coverage', + 'sphinx.ext.ifconfig', + 'sphinx.ext.graphviz', + 'sphinx.ext.todo', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = [] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + + +# openstackdocstheme options +repository_name = 'x/devstack-plugin-tobiko' +bug_project = 'tobiko' +bug_tag = 'doc' + +# Set to True if using StoryBoard +use_storyboard = True + +todo_include_todos = True + + +# -- 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 = "sphinx_rtd_theme" + +# 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 = { + "canonical_url": "https://docs.openstack.org/tobiko/latest/", + "logo_only": False, + "display_version": True, + "prev_next_buttons_location": "top", + "style_external_links": True, + # Toc options + "collapse_navigation": True, + "sticky_navigation": True, + "navigation_depth": 4, + "includehidden": True, + "titles_only": False, +} + + +# 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'] diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..a6210d3 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1 @@ +.. include:: ../../README.rst diff --git a/tox.ini b/tox.ini index 5f8ebbd..1262c60 100644 --- a/tox.ini +++ b/tox.ini @@ -1,11 +1,12 @@ [tox] skipsdist = True -envlist = linters +envlist = linters,docs minversion = 3.8.0 [testenv] usedevelop=False +skip_install = true [testenv:linters] @@ -17,3 +18,11 @@ commands = pre-commit autoupdate pre-commit run --all-files pre-commit install + + +[testenv:docs] +deps = + -r{toxinidir}/doc/requirements.txt +changedir = doc/source +commands = + sphinx-build -W -b html . ../build/html diff --git a/zuul.d/project.yaml b/zuul.d/project.yaml index 798e973..e8fcf51 100644 --- a/zuul.d/project.yaml +++ b/zuul.d/project.yaml @@ -2,12 +2,9 @@ - project: templates: + - ansible-role-jobs - devstack-tobiko-gate - gate: - jobs: - - openstack-tox-linters - check: &pipeline jobs: - openstack-tox-linters