Add API Documentation structure

Change-Id: Ie99c6118dff88b2b8e614f732391793b54bb91f0
Signed-off-by: Gael Chamoulaud (Strider) <gchamoul@redhat.com>

.gitignore

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

doc/requirements.txt

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

doc/source/conf.py

@@ -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'
+    ),
+]

doc/source/contributor/contributing.rst

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

doc/source/contributor/index.rst

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

doc/source/contributor/testing.rst

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

doc/source/index.rst

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

doc/source/reference/index.rst

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

lower-constraints.txt

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

test-requirements.txt

@@ -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 # BSD
-sphinx>=1.8.0,!=2.1.0;python_version>='3.4' # 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

tox.ini

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

zuul.d/layout.yaml

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