diff --git a/README.rst b/README.rst index 9f7ef37e3..ca6e21b3f 100644 --- a/README.rst +++ b/README.rst @@ -2,11 +2,22 @@ Tobiko ====== -Framework to write Python test cases to test cloud (OpenStack) system operations. -* Free software: Apache License v2.0 +Test Big Cloud Operations +------------------------- + +Tobiko is a project used to write system tests for OpenStack. Main projects +goals are: + +- Provide a Python framewor to write system scenario test cases +- Provide CLI tools to implement a workflow designed to test potentially + destructive operations. + +Links +~~~~~ + +* License: `Apache License v2.0 `__ +* Documentation: `Tobiko Documentation `__ * Source: https://opendev.org/x/tobiko.git -* Bugs: https://storyboard.openstack.org/#!/project/x/tobiko -* Usage: https://opendev.org/x/tobiko/src/branch/master/docs/quick-start.md - - +* Bugs: `StoryBoard `__ +* Usage: `Quick Start Guide `__ diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 000000000..69fe55ecf --- /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) \ No newline at end of file diff --git a/docs/quick-start.md b/doc/quick-start.md similarity index 100% rename from docs/quick-start.md rename to doc/quick-start.md diff --git a/docs/requirements.txt b/doc/requirements.txt similarity index 51% rename from docs/requirements.txt rename to doc/requirements.txt index f003005fd..83bf052a6 100644 --- a/docs/requirements.txt +++ b/doc/requirements.txt @@ -1,6 +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. -sphinx!=1.6.6,>=1.6.2 # BSD -oslotest>=3.2.0 # Apache-2.0 -reno>=2.5.0 # Apache-2.0 + +openstackdocstheme>=1.18.1 # Apache-2.0 +oslotest>=3.2.0 # Apache-2.0 +oslo.log>=3.36.0 # Apache-2.0 +reno>=2.5.0 # Apache-2.0 +sphinx!=1.6.6,>=1.6.2 # BSD diff --git a/doc/source/_static/README.txt b/doc/source/_static/README.txt new file mode 100644 index 000000000..f1591f14c --- /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 000000000..8d70df45a --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,83 @@ +# 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 +import sys +BASE_DIR = os.path.dirname(os.path.abspath(__file__)) +TOBIKO_DIR = os.path.abspath(os.path.join(BASE_DIR, "..", "..")) +sys.path.insert(0, TOBIKO_DIR) + + +# -- Project information ----------------------------------------------------- + +project = 'Tobiko' +copyright = "2019, Red Hat" +author = "Tobiko's Team" + +# 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. +# +# Version info +from tobiko import version +release = version.release +# The short X.Y version. +version = version.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', + 'openstackdocstheme', +# 'support_matrix', +# 'oslo_config.sphinxext', +# 'oslo_config.sphinxconfiggen', +# 'oslo_policy.sphinxext', +# 'oslo_policy.sphinxpolicygen', +] + +# 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/tobiko' +bug_project = 'tobiko' +bug_tag = 'doc' + +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 = 'default' + +# 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/contributor/index.rst b/doc/source/contributor/index.rst new file mode 100644 index 000000000..298305c4b --- /dev/null +++ b/doc/source/contributor/index.rst @@ -0,0 +1,24 @@ +.. + 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. + + Convention for heading levels in Tobiko lib devref: + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + (Avoid deeper levels because they do not render well.) + + +Project Contributor Guide +========================= diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 000000000..2868c00e0 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,51 @@ +Welcome to Tobiko Documentation! +================================ + + +Test Big Cloud Operations +------------------------- + +Tobiko is a project used to write system tests for OpenStack. Main projects +goals are: + +- Provide a Python framewor to write system scenario test cases +- Provide CLI tools to implement a workflow designed to test potentially + destructive operations. + +Links +~~~~~ + +* License: `Apache License v2.0 `__ +* Documentation: `Tobiko Documentation `__ +* Source: https://opendev.org/x/tobiko.git +* Bugs: `StoryBoard `__ +* Usage: `Quick Start Guide `__ + + +Document Overview +----------------- + +This document describes the tools for final user and contributors of the +project, and assumes that you are already familiar with OpenStack from an +end-user perspective. If not, hop over to the +`OpenStack doc site `__ + +You can look for additional documentation also in the +`OpenStack wiki `__ + +This documentation is generated by the Sphinx toolkit and lives in the source +tree. + +Enjoy! + +.. toctree:: + :maxdepth: 2 + + install/index + user/index + contributor/index + +.. toctree:: + :maxdepth: 1 + + reference/index diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst new file mode 100644 index 000000000..878e26580 --- /dev/null +++ b/doc/source/install/index.rst @@ -0,0 +1,48 @@ +============ +Installation +============ + + +Document Overview +----------------- + +This document describes how to install Tobiko inside a Python virtualenv. For +a quick and simpler start you can jump to the Quick Start Guide. + + +Install Tobiko Using Virtualenv +------------------------------- + +Make sure Gcc, Git and base Python packages are installed on your system. +For instance on RHEL Linux you could type:: + + sudo yum install -y gcc git python python-devel + +Make sure pip and setuptools are installed and up-to date:: + + wget https://bootstrap.pypa.io/get-pip.py + sudo python get-pip.py + sudo pip install --upgrade setuptools + +Make sure tox, virtualenv and wheel are installed and up to date:: + + sudo pip install --upgrade tox virtualenv wheel + +Get Tobiko source code using Git:: + + git clone https://opendev.org/x/tobiko.git + cd tobiko + +To install Tobiko and its dependencies is safer to create a clean Virtualenv +where to install it. Create a Virtualenv and activate it:: + + virtualenv .tobiko-env + source .tobiko-env/bin/activate + +Install Tobiko and its requirements:: + + pip install \ + -c https://opendev.org/openstack/requirements/raw/branch/master/upper-constraints.txt \ + -r requirements.txt \ + -r extra-requirements.txt + pip install . diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst new file mode 100644 index 000000000..9f7c08b5e --- /dev/null +++ b/doc/source/reference/index.rst @@ -0,0 +1,30 @@ +.. + 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. + + Convention for heading levels in Neutron lib devref: + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + (Avoid deeper levels because they do not render well.) + +================================ +Tobiko Framework Reference Guide +================================ + +.. toctree:: + :maxdepth: 1 + +* :ref:`genindex` +* :ref:`search` diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst new file mode 100644 index 000000000..e1ad97a0b --- /dev/null +++ b/doc/source/user/index.rst @@ -0,0 +1,3 @@ +================= +Tobiko User Guide +================= diff --git a/docs/usage.md b/doc/usage.md similarity index 100% rename from docs/usage.md rename to doc/usage.md diff --git a/docs/installation.md b/docs/installation.md deleted file mode 100644 index 876b43a01..000000000 --- a/docs/installation.md +++ /dev/null @@ -1,28 +0,0 @@ -# Tobiko installation guide - -## Install pip - -curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py -sudo python get-pip.py - -## Install Virtual Environment - -sudo pip install virtualenv - -## Install dependencies - -sudo yum install gcc python-devel - -## Clone Tobiko - -git clone https://review.openstack.org/openstack/tobiko.git - -## Create Virtual Environment - -virtualenv ~/tobiko_venv && source ~/tobiko_venv/bin/activate - -## Install Tobiko - -cd tobiko -pip install -r extra-requirements.txt -pip install . \ No newline at end of file diff --git a/releasenotes/source/conf.py b/releasenotes/source/conf.py index 0b4ed6af9..ef384c8d8 100644 --- a/releasenotes/source/conf.py +++ b/releasenotes/source/conf.py @@ -12,20 +12,28 @@ # 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('.')) +import os +import sys +BASE_DIR = os.path.dirname(os.path.abspath(__file__)) +TOBIKO_DIR = os.path.abspath(os.path.join(BASE_DIR, "..", "..")) +sys.path.insert(0, TOBIKO_DIR) # -- Project information ----------------------------------------------------- project = u'Tobiko Release Notes' -copyright = u'2019, Tobiko developers' +copyright = "2019, Red Hat" +author = "Tobiko's Team" -# The short X.Y version -version = u'' -# The full version, including alpha/beta/rc tags -release = u'' +# 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. +# +# Version info +from tobiko import version +release = version.release +# The short X.Y version. +version = version.version # -- General configuration --------------------------------------------------- @@ -38,11 +46,12 @@ release = u'' # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + 'openstackdocstheme', 'reno.sphinxext', ] # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = [] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: diff --git a/requirements.txt b/requirements.txt index 14504f29a..f3f55c2b4 100644 --- a/requirements.txt +++ b/requirements.txt @@ -7,6 +7,7 @@ netaddr>=0.7.18 # BSD neutron-lib>=1.25.0 # Apache-2.0 oslo.config>=5.2.0 # Apache-2.0 oslo.log>=3.36.0 # Apache-2.0 +pbr>=4.0.0 # Apache-2.0 python-heatclient>=1.5.0 # Apache-2.0 python-neutronclient>=6.7.0 # Apache-2.0 python-novaclient>=9.1.0 # Apache-2.0 diff --git a/tobiko/version.py b/tobiko/version.py new file mode 100644 index 000000000..a31bebe97 --- /dev/null +++ b/tobiko/version.py @@ -0,0 +1,30 @@ +# +# 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. +from __future__ import absolute_import + +import sys + +import pbr.version + + +version_info = pbr.version.VersionInfo('tobiko') + +release = version_info.release_string() +version = version_info.version_string() + + +if __name__ == '__main__': + message = ("release: {release}\n" + "version: {version}\n").format( + release=release, version=version) + sys.stdout.write(message) diff --git a/tox.ini b/tox.ini index 108503839..7632a65b6 100644 --- a/tox.ini +++ b/tox.ini @@ -1,5 +1,5 @@ [tox] -envlist = pep8,pylint,py36,py27 +envlist = pep8,pylint,py36,py27,docs minversion = 2.3.2 @@ -161,13 +161,27 @@ setenv = {[testenv:scenario]setenv} # --- documentation environments --------------------------------------------- +[testenv:docs] + +basepython = python3 +envdir = {toxworkdir}/docs +deps = -r{toxinidir}/doc/requirements.txt +commands = sphinx-build -W -b html doc/source doc/build/html + + +[testenv:linkcheck] + +basepython = python3 +envdir = {toxworkdir}/docs +deps = {[testenv:docs]deps} +commands = sphinx-build -W -b linkcheck doc/source doc/build/linkcheck + [testenv:releasenotes] basepython = python3 - -deps = -r{toxinidir}/docs/requirements.txt - +envdir = {toxworkdir}/docs +deps = {[testenv:docs]deps} commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html diff --git a/zuul.d/project.yaml b/zuul.d/project.yaml index 967947ed4..a8d7289bb 100644 --- a/zuul.d/project.yaml +++ b/zuul.d/project.yaml @@ -8,6 +8,7 @@ - openstack-python37-jobs - release-notes-jobs-python3 - publish-to-pypi + - publish-openstack-docs-pti check: jobs: - openstack-tox-pylint