Create docs job and environment

- Add docs CI job and Tox environment
- Create RST documentation sckeleton
- Use OpenStack theme for releasenotes job.
- Move docs/ code to doc/ folder to conform to OpenStack standards.

Change-Id: I8b917abe46125fec32076637a041a728257fa96a

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 <https://opendev.org/x/tobiko/src/branch/master/LICENSE>`__
+* Documentation: `Tobiko Documentation <https://docs.openstack.org/>`__
 * Source: https://opendev.org/x/tobiko.git
-* Bugs: https://storyboard.openstack.org/#!/project/x/tobiko
+* Bugs: `StoryBoard <https://storyboard.openstack.org/#!/project/x/tobiko>`__
-* Usage: https://opendev.org/x/tobiko/src/branch/master/docs/quick-start.md
+* Usage: `Quick Start Guide <https://opendev.org/x/tobiko/src/branch/master/doc/quick-start.md>`__
-
-

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)

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
+openstackdocstheme>=1.18.1  # Apache-2.0
-reno>=2.5.0 # 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

doc/source/_static/README.txt

@@ -0,0 +1 @@
+This file is here only to make sure this folder exists on Git repository.

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']

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
+=========================

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 <https://opendev.org/x/tobiko/src/branch/master/LICENSE>`__
+* Documentation: `Tobiko Documentation <https://docs.openstack.org/>`__
+* Source: https://opendev.org/x/tobiko.git
+* Bugs: `StoryBoard <https://storyboard.openstack.org/#!/project/x/tobiko>`__
+* Usage: `Quick Start Guide <https://opendev.org/x/tobiko/src/branch/master/doc/quick-start.md>`__
+
+
+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 <https://docs.openstack.org/>`__
+
+You can look for additional documentation also in the
+`OpenStack wiki <http://wiki.openstack.org/>`__
+
+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

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 .

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`

doc/source/user/index.rst

@@ -0,0 +1,3 @@
+=================
+Tobiko User Guide
+=================

docs/installation.md

@@ -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 .

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 os
-# import sys
+import sys
-# sys.path.insert(0, os.path.abspath('.'))
+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
+# The version info for the project you're documenting, acts as replacement for
-version = u''
+# |version| and |release|, also used in various other places throughout the
-# The full version, including alpha/beta/rc tags
+# built documents.
-release = u''
+#
+# 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:

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

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)

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
-
+envdir = {toxworkdir}/docs
-deps = -r{toxinidir}/docs/requirements.txt
+deps = {[testenv:docs]deps}
-
 commands =
     sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
 

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