Merge "Add API Documentation structure"

This commit is contained in:
Zuul 2020-05-14 17:31:25 +00:00 committed by Gerrit Code Review
commit 4f57229c23
12 changed files with 232 additions and 3 deletions

1
.gitignore vendored
View File

@ -45,6 +45,7 @@ output/*/index.html
# Sphinx
doc/build
doc/source/reference/api/
# pbr generates these
AUTHORS

6
doc/requirements.txt Normal file
View File

@ -0,0 +1,6 @@
# this is required for the docs build jobs
sphinx>=1.8.0,<2.0.0;python_version=='2.7' # BSD
sphinx>=1.8.0,!=2.1.0;python_version>='3.4' # BSD
openstackdocstheme>=1.20.0 # Apache-2.0
doc8>=0.8.0 # Apache-2.0
sphinxcontrib-apidoc>=0.2.0 # BSD

80
doc/source/conf.py Normal file
View File

@ -0,0 +1,80 @@
# -- 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 = ['sphinxcontrib.apidoc',
'sphinx.ext.viewcode',
'openstackdocstheme',
]
# sphinxcontrib.apidoc options
apidoc_module_dir = '../../validations_libs'
apidoc_output_dir = 'reference/api'
apidoc_excluded_paths = []
apidoc_separate_modules = True
# openstackdocstheme options
repository_name = 'openstack/validations-libs'
use_storyboard = True
# 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
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# General information about the project.
copyright = u'OpenStack Foundation'
# A list of ignored prefixes for module index sorting.
modindex_common_prefix = ['validations_libs.']
# 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 = 'sphinx'
# A list of glob-style patterns that should be excluded when looking for
# source files. They are matched against the source file names relative to the
# source directory, using slashes as directory separators on all platforms.
exclude_patterns = ['']
# -- 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 = '_theme'
# html_static_path = ['_static']
html_theme = 'openstackdocs'
# Output file base name for HTML help builder.
htmlhelp_basename = 'validations-libsdoc'
latex_use_xindy = False
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass
# [howto/manual]).
latex_documents = [
(
'index',
'doc-validations-libs.tex',
u'Validations Framework Client Documentation',
u'OpenStack LLC',
'manual'
),
]

View File

@ -0,0 +1,40 @@
.. _contributing:
================================
Contributing to validations-libs
================================
If you're interested in contributing to the validations-libs project,
the following will help get you started.
#tripleo on Freenode IRC Network
--------------------------------
There is a very active chat channel at irc://freenode.net/#tripleo.
This is usually the best place to ask questions and find your way around.
IRC stands for Internet Relay Chat and it is a way to chat online in real
time. You can ask a question and come back later to read the answer in the
log files. Logs for the #tripleo IRC channel are stored at
http://eavesdrop.openstack.org/irclogs/%23tripleo/.
Contributor License Agreement
-----------------------------
.. index::
single: license; agreement
In order to contribute to the validations-libs project, you need to have
signed OpenStack's contributor's agreement.
.. seealso::
* https://docs.openstack.org/infra/manual/developers.html
* https://wiki.openstack.org/wiki/CLA
Project Hosting Details
-----------------------
Code Hosting
https://opendev.org/openstack/validations-libs
Code Review
https://review.opendev.org/#/q/status:open+project:openstack/validations-libs,n,z

View File

@ -0,0 +1,8 @@
==========================================
validations-libs Contributor Documentation
==========================================
.. toctree::
contributing
testing

View File

@ -0,0 +1,32 @@
.. _testing:
=======
Testing
=======
Python Guideline Enforcement
............................
All code has to pass the pep8 style guideline to merge into OpenStack, to
validate the code against these guidelines you can run::
$ tox -e pep8
Unit Testing
............
It is strongly encouraged to run the unit tests locally under one or more
test environments prior to submitting a patch. To run all the recommended
environments sequentially and pep8 style guideline run::
$ tox
You can also selectively pick specific test environments by listing your
chosen environments after a -e flag::
$ tox -e py36,py38,pep8
.. note::
Tox sets up virtual environment and installs all necessary dependencies.
Sharing the environment with devstack testing is not recommended due to
conflicting configuration with system dependencies.

24
doc/source/index.rst Normal file
View File

@ -0,0 +1,24 @@
================================
Validations Framework Client API
================================
This is the Validations Framework Client API. It provides:
* a Python API: the ``validations_libs`` module, to
* list and run validation(s) on node(s).
Contents
========
.. toctree::
:maxdepth: 2
contributor/index
reference/index
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

View File

@ -0,0 +1,8 @@
==========================================
Full Validations-libs Python API Reference
==========================================
.. toctree::
:maxdepth: 1
api/modules

View File

@ -103,6 +103,7 @@ six==1.11.0
smmap2==2.0.3
snowballstemmer==1.2.1
Sphinx==1.8.0
sphinxcontrib-apidoc==0.2.0
sphinxcontrib-websupport==1.0.1
stestr==1.0.0
stevedore==1.28.0

View File

@ -7,8 +7,8 @@ hacking>=3.0,<3.1.0 # Apache-2.0
coverage!=4.4,>=4.0 # Apache-2.0
python-subunit>=1.0.0 # Apache-2.0/BSD
sphinx>=1.8.0,<2.0.0;python_version=='2.7' # BSD
sphinx>=1.8.0,!=2.1.0;python_version>='3.4' # BSD
sphinx>=1.8.0,!=2.1.0 # BSD
sphinxcontrib-apidoc>=0.2.0 # BSD
stestr>=1.0.0 # Apache-2.0
testscenarios>=0.4 # Apache-2.0/BSD
testtools>=2.2.0 # MIT

23
tox.ini
View File

@ -1,6 +1,6 @@
[tox]
minversion = 3.2.0
envlist = linters,py38
envlist = linters,docs,py38
skipdist = True
[testenv]
@ -63,6 +63,27 @@ deps =
-r {toxinidir}/test-requirements.txt
commands = python setup.py test --coverage --testr-args='{posargs}'
[testenv:docs]
deps =
-r {toxinidir}/requirements.txt
-r {toxinidir}/test-requirements.txt
-r {toxinidir}/doc/requirements.txt
commands=
sphinx-build -W -b html doc/source doc/build/html
doc8 doc
[testenv:pdf-docs]
whitelist_externals = make
deps = {[testenv:docs]deps}
commands =
sphinx-build -W -b latex doc/source doc/build/pdf
make -C doc/build/pdf
[doc8]
# Settings for doc8:
extensions = .rst
ignore = D001
[testenv:lower-constraints]
deps =
-c{toxinidir}/lower-constraints.txt

View File

@ -7,6 +7,10 @@
jobs:
- openstack-tox-linters: &tripleo-linters
nodeset: centos-8
- openstack-tox-docs: &tripleo-docs
files:
- ^doc/.*
- ^README.rst
- tripleo-ci-centos-8-containers-multinode: &containers_multinode
dependencies: &deps
- openstack-tox-linters
@ -25,5 +29,9 @@
gate:
jobs:
- openstack-tox-linters: *tripleo-linters
- openstack-tox-docs: *tripleo-docs
- tripleo-ci-centos-8-containers-multinode: *containers_multinode
- tripleo-ci-centos-8-standalone: *basic_standalone
promote:
jobs:
- promote-openstack-tox-docs: *tripleo-docs