From 7b14f9c22dd79fe28d710e37d9a70d7e4b7bb293 Mon Sep 17 00:00:00 2001 From: "Gael Chamoulaud (Strider)" Date: Mon, 27 Apr 2020 11:52:40 +0200 Subject: [PATCH] Add API Documentation structure Change-Id: Ie99c6118dff88b2b8e614f732391793b54bb91f0 Signed-off-by: Gael Chamoulaud (Strider) --- .gitignore | 1 + doc/requirements.txt | 6 ++ doc/source/conf.py | 80 +++++++++++++++++++++++++ doc/source/contributor/contributing.rst | 40 +++++++++++++ doc/source/contributor/index.rst | 8 +++ doc/source/contributor/testing.rst | 32 ++++++++++ doc/source/index.rst | 24 ++++++++ doc/source/reference/index.rst | 8 +++ lower-constraints.txt | 1 + test-requirements.txt | 4 +- tox.ini | 23 ++++++- zuul.d/layout.yaml | 8 +++ 12 files changed, 232 insertions(+), 3 deletions(-) create mode 100644 doc/requirements.txt create mode 100644 doc/source/conf.py create mode 100644 doc/source/contributor/contributing.rst create mode 100644 doc/source/contributor/index.rst create mode 100644 doc/source/contributor/testing.rst create mode 100644 doc/source/index.rst create mode 100644 doc/source/reference/index.rst diff --git a/.gitignore b/.gitignore index 476c0d97..00453264 100644 --- a/.gitignore +++ b/.gitignore @@ -45,6 +45,7 @@ output/*/index.html # Sphinx doc/build +doc/source/reference/api/ # pbr generates these AUTHORS diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 00000000..4d7c9a38 --- /dev/null +++ b/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 diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 00000000..7e7d28cb --- /dev/null +++ b/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' + ), +] diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst new file mode 100644 index 00000000..377aa1d1 --- /dev/null +++ b/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 diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst new file mode 100644 index 00000000..30bca25f --- /dev/null +++ b/doc/source/contributor/index.rst @@ -0,0 +1,8 @@ +========================================== +validations-libs Contributor Documentation +========================================== + +.. toctree:: + + contributing + testing diff --git a/doc/source/contributor/testing.rst b/doc/source/contributor/testing.rst new file mode 100644 index 00000000..62228aa7 --- /dev/null +++ b/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. diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 00000000..03a7f1a8 --- /dev/null +++ b/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` diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst new file mode 100644 index 00000000..bccfc035 --- /dev/null +++ b/doc/source/reference/index.rst @@ -0,0 +1,8 @@ +========================================== +Full Validations-libs Python API Reference +========================================== + +.. toctree:: + :maxdepth: 1 + + api/modules diff --git a/lower-constraints.txt b/lower-constraints.txt index a286a1d5..37036a4e 100644 --- a/lower-constraints.txt +++ b/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 diff --git a/test-requirements.txt b/test-requirements.txt index b843aee7..0d58bb5c 100644 --- a/test-requirements.txt +++ b/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;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 diff --git a/tox.ini b/tox.ini index bfa39659..98569e47 100644 --- a/tox.ini +++ b/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 diff --git a/zuul.d/layout.yaml b/zuul.d/layout.yaml index 823faf11..3064102e 100644 --- a/zuul.d/layout.yaml +++ b/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