Browse Source

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
changes/53/655353/13
Federico Ressi 2 years ago
parent
commit
08d12255aa
  1. 21
      README.rst
  2. 19
      doc/Makefile
  3. 0
      doc/quick-start.md
  4. 9
      doc/requirements.txt
  5. 1
      doc/source/_static/README.txt
  6. 83
      doc/source/conf.py
  7. 24
      doc/source/contributor/index.rst
  8. 51
      doc/source/index.rst
  9. 48
      doc/source/install/index.rst
  10. 30
      doc/source/reference/index.rst
  11. 3
      doc/source/user/index.rst
  12. 0
      doc/usage.md
  13. 28
      docs/installation.md
  14. 27
      releasenotes/source/conf.py
  15. 1
      requirements.txt
  16. 30
      tobiko/version.py
  17. 20
      tox.ini
  18. 1
      zuul.d/project.yaml

21
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
* 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
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>`__

19
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)

0
docs/quick-start.md → doc/quick-start.md

9
docs/requirements.txt → 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

1
doc/source/_static/README.txt

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

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

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

51
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

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

30
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`

3
doc/source/user/index.rst

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

0
docs/usage.md → doc/usage.md

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

27
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:

1
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

30
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)

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

1
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

Loading…
Cancel
Save