Moving doc structure closer to that in validations-commons.
After merge of 723586 anyway. Specific changes include: new readme.rst in doc structure tox adjustment license info bugtracking and source links date update badges CONTRIBUTING.rst ansible_autodoc.py release notes infrastructure Signed-off-by: Jiri Podivin <jpodivin@redhat.com> Change-Id: Ia3db253e05d0f8d754259ff841a783f29cd6a70f
This commit is contained in:
parent
18d1a759e5
commit
bcd6d6e857
19
CONTRIBUTING.rst
Normal file
19
CONTRIBUTING.rst
Normal file
@ -0,0 +1,19 @@
|
|||||||
|
Contributions to validations-libs follow guidelines largely similar
|
||||||
|
to those of other openstack projects.
|
||||||
|
|
||||||
|
If you're interested in contributing to the validations-libs project,
|
||||||
|
the following will help get you started:
|
||||||
|
|
||||||
|
https://docs.openstack.org/infra/manual/developers.html
|
||||||
|
|
||||||
|
If you already have a good understanding of how the system works and your
|
||||||
|
OpenStack accounts are set up, you can skip to the development workflow
|
||||||
|
section of this documentation to learn how changes to OpenStack should be
|
||||||
|
submitted for review via the Gerrit tool:
|
||||||
|
|
||||||
|
https://docs.openstack.org/infra/manual/developers.html#development-workflow
|
||||||
|
|
||||||
|
Pull requests submitted through GitHub will be ignored.
|
||||||
|
|
||||||
|
Validations are meant to verify functionality of tripleo systems.
|
||||||
|
Therefore a special care should be given to testing your code before submitting a review.
|
18
README.rst
18
README.rst
@ -2,8 +2,24 @@
|
|||||||
validations-libs
|
validations-libs
|
||||||
================
|
================
|
||||||
|
|
||||||
|
.. image:: https://governance.openstack.org/tc/badges/validations-libs.svg
|
||||||
|
:target: https://governance.openstack.org/tc/reference/tags/index.html
|
||||||
|
|
||||||
A collection of python libraries for the Validation Framework
|
A collection of python libraries for the Validation Framework
|
||||||
|
|
||||||
|
The validations will help detect issues early in the deployment process and
|
||||||
|
prevent field engineers from wasting time on misconfiguration or hardware
|
||||||
|
issues in their environments.
|
||||||
|
|
||||||
|
* Free software: Apache_license_
|
||||||
|
* Documentation: https://docs.openstack.org/validations-libs/latest/
|
||||||
|
* Source: https://opendev.org/openstack/validations-libs
|
||||||
|
* Bugs - Upstream: https://bugs.launchpad.net/tripleo/+bugs?field.tag=validations
|
||||||
|
* Bugs - Downstream: https://bugzilla.redhat.com/buglist.cgi?component=validations-libs&product=Red%20Hat%20OpenStack
|
||||||
|
|
||||||
|
.. * Release notes: https://docs.openstack.org/releasenotes/validations-libs/ We don't have any yet.
|
||||||
|
|
||||||
|
|
||||||
Development Environment Setup
|
Development Environment Setup
|
||||||
=============================
|
=============================
|
||||||
|
|
||||||
@ -42,3 +58,5 @@ Then you can run the container and start to run some builtin Validations::
|
|||||||
Then run validations::
|
Then run validations::
|
||||||
|
|
||||||
validation.py run --validation check-ftype,512e --inventory /etc/ansible/hosts
|
validation.py run --validation check-ftype,512e --inventory /etc/ansible/hosts
|
||||||
|
|
||||||
|
.. _Apache_license: http://www.apache.org/licenses/LICENSE-2.0
|
||||||
|
@ -3,3 +3,4 @@ sphinx>=2.0.0,!=2.1.0 # BSD
|
|||||||
openstackdocstheme>=2.2.2 # Apache-2.0
|
openstackdocstheme>=2.2.2 # Apache-2.0
|
||||||
doc8>=0.8.0 # Apache-2.0
|
doc8>=0.8.0 # Apache-2.0
|
||||||
sphinxcontrib-apidoc>=0.2.0 # BSD
|
sphinxcontrib-apidoc>=0.2.0 # BSD
|
||||||
|
reno>=3.1.0 # Apache-2.0
|
||||||
|
384
doc/source/_exts/ansible-autodoc.py
Normal file
384
doc/source/_exts/ansible-autodoc.py
Normal file
@ -0,0 +1,384 @@
|
|||||||
|
# Copyright 2021 Red Hat, Inc.
|
||||||
|
# All Rights Reserved.
|
||||||
|
#
|
||||||
|
# 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.
|
||||||
|
|
||||||
|
|
||||||
|
import imp
|
||||||
|
import os
|
||||||
|
|
||||||
|
from docutils import core
|
||||||
|
from docutils import nodes
|
||||||
|
from docutils.parsers.rst import Directive
|
||||||
|
from docutils.parsers import rst
|
||||||
|
from docutils.writers.html4css1 import Writer
|
||||||
|
|
||||||
|
from sphinx import addnodes
|
||||||
|
|
||||||
|
import yaml
|
||||||
|
|
||||||
|
try:
|
||||||
|
import io
|
||||||
|
StringIO = io.StringIO
|
||||||
|
except ImportError:
|
||||||
|
import StringIO
|
||||||
|
|
||||||
|
|
||||||
|
class DocYaml:
|
||||||
|
"""
|
||||||
|
Wrapper clas around calls to yaml lib.
|
||||||
|
"""
|
||||||
|
def _license_filter(self, data):
|
||||||
|
"""This will filter out our boilerplate license heading in return data.
|
||||||
|
|
||||||
|
The filter is used to allow documentation we're creating in variable
|
||||||
|
files to be rendered more beautifully.
|
||||||
|
"""
|
||||||
|
lines = []
|
||||||
|
mark = True
|
||||||
|
for line in data.splitlines():
|
||||||
|
if '# Copyright' in line:
|
||||||
|
mark = False
|
||||||
|
if mark:
|
||||||
|
lines.append(line)
|
||||||
|
if '# under the License' in line:
|
||||||
|
mark = True
|
||||||
|
return '\n'.join(lines)
|
||||||
|
|
||||||
|
def dump(self, data, stream=None, **kw):
|
||||||
|
if not stream:
|
||||||
|
stream = StringIO()
|
||||||
|
try:
|
||||||
|
yaml.dump(data=data, stream=stream, Dumper=yaml.Dumper, **kw)
|
||||||
|
return self._license_filter(stream.getvalue().strip())
|
||||||
|
finally:
|
||||||
|
stream.close()
|
||||||
|
|
||||||
|
def load(self, data):
|
||||||
|
return yaml.load(data, Loader=yaml.Loader)
|
||||||
|
|
||||||
|
DOCYAML = DocYaml()
|
||||||
|
|
||||||
|
|
||||||
|
class AnsibleAutoPluginDirective(Directive):
|
||||||
|
directive_name = "ansibleautoplugin"
|
||||||
|
has_content = True
|
||||||
|
option_spec = {
|
||||||
|
'module': rst.directives.unchanged,
|
||||||
|
'role': rst.directives.unchanged,
|
||||||
|
'documentation': rst.directives.unchanged,
|
||||||
|
'examples': rst.directives.unchanged
|
||||||
|
}
|
||||||
|
|
||||||
|
@staticmethod
|
||||||
|
def _render_html(source):
|
||||||
|
return core.publish_parts(
|
||||||
|
source=source,
|
||||||
|
writer=Writer(),
|
||||||
|
writer_name='html',
|
||||||
|
settings_overrides={'no_system_messages': True}
|
||||||
|
)
|
||||||
|
|
||||||
|
def make_node(self, title, contents, content_type=None):
|
||||||
|
section = self._section_block(title=title)
|
||||||
|
if not content_type:
|
||||||
|
# Doc section
|
||||||
|
for content in contents['docs']:
|
||||||
|
for paragraph in content.split('\n'):
|
||||||
|
retnode = nodes.paragraph()
|
||||||
|
retnode.append(self._raw_html_block(data=paragraph))
|
||||||
|
section.append(retnode)
|
||||||
|
|
||||||
|
# Options Section
|
||||||
|
options_list = nodes.field_list()
|
||||||
|
options_section = self._section_block(title='Options')
|
||||||
|
for key, value in contents['options'].items():
|
||||||
|
options_list.append(
|
||||||
|
self._raw_fields(
|
||||||
|
data=value['description'],
|
||||||
|
field_name=key
|
||||||
|
)
|
||||||
|
)
|
||||||
|
else:
|
||||||
|
options_section.append(options_list)
|
||||||
|
section.append(options_section)
|
||||||
|
|
||||||
|
# Authors Section
|
||||||
|
authors_list = nodes.field_list()
|
||||||
|
authors_list.append(
|
||||||
|
self._raw_fields(
|
||||||
|
data=contents['author']
|
||||||
|
)
|
||||||
|
)
|
||||||
|
authors_section = self._section_block(title='Authors')
|
||||||
|
authors_section.append(authors_list)
|
||||||
|
section.append(authors_section)
|
||||||
|
|
||||||
|
elif content_type == 'yaml':
|
||||||
|
for content in contents:
|
||||||
|
section.append(
|
||||||
|
self._literal_block(
|
||||||
|
data=content,
|
||||||
|
dump_data=False
|
||||||
|
)
|
||||||
|
)
|
||||||
|
|
||||||
|
return section
|
||||||
|
|
||||||
|
@staticmethod
|
||||||
|
def load_module(filename):
|
||||||
|
return imp.load_source('__ansible_module__', filename)
|
||||||
|
|
||||||
|
@staticmethod
|
||||||
|
def build_documentation(module):
|
||||||
|
docs = DOCYAML.load(module.DOCUMENTATION)
|
||||||
|
doc_data = dict()
|
||||||
|
doc_data['docs'] = docs['description']
|
||||||
|
doc_data['author'] = docs.get('author', list())
|
||||||
|
doc_data['options'] = docs.get('options', dict())
|
||||||
|
return doc_data
|
||||||
|
|
||||||
|
@staticmethod
|
||||||
|
def build_examples(module):
|
||||||
|
examples = DOCYAML.load(module.EXAMPLES)
|
||||||
|
return_examples = list()
|
||||||
|
for example in examples:
|
||||||
|
return_examples.append(DOCYAML.dump([example]))
|
||||||
|
return return_examples
|
||||||
|
|
||||||
|
def _raw_html_block(self, data):
|
||||||
|
html = self._render_html(source=data)
|
||||||
|
return nodes.raw('', html['body'], format='html')
|
||||||
|
|
||||||
|
def _raw_fields(self, data, field_name=''):
|
||||||
|
body = nodes.field_body()
|
||||||
|
if isinstance(data, list):
|
||||||
|
for item in data:
|
||||||
|
body.append(self._raw_html_block(data=item))
|
||||||
|
else:
|
||||||
|
body.append(self._raw_html_block(data=data))
|
||||||
|
|
||||||
|
field = nodes.field()
|
||||||
|
field.append(nodes.field_name(text=field_name))
|
||||||
|
field.append(body)
|
||||||
|
return field
|
||||||
|
|
||||||
|
@staticmethod
|
||||||
|
def _literal_block(data, language='yaml', dump_data=True):
|
||||||
|
if dump_data:
|
||||||
|
literal = nodes.literal_block(
|
||||||
|
text=DOCYAML.dump(data)
|
||||||
|
)
|
||||||
|
else:
|
||||||
|
literal = nodes.literal_block(text=data)
|
||||||
|
literal['language'] = 'yaml'
|
||||||
|
return literal
|
||||||
|
|
||||||
|
@staticmethod
|
||||||
|
def _section_block(title, text=None):
|
||||||
|
section = nodes.section(
|
||||||
|
title,
|
||||||
|
nodes.title(text=title),
|
||||||
|
ids=[nodes.make_id('-'.join(title))],
|
||||||
|
)
|
||||||
|
if text:
|
||||||
|
section_body = nodes.field_body()
|
||||||
|
section_body.append(nodes.paragraph(text=text))
|
||||||
|
section.append(section_body)
|
||||||
|
|
||||||
|
return section
|
||||||
|
|
||||||
|
def _yaml_section(self, to_yaml_data, section_title, section_text=None):
|
||||||
|
yaml_section = self._section_block(
|
||||||
|
title=section_title,
|
||||||
|
text=section_text
|
||||||
|
)
|
||||||
|
yaml_section.append(self._literal_block(data=to_yaml_data))
|
||||||
|
return yaml_section
|
||||||
|
|
||||||
|
def _run_role(self, role):
|
||||||
|
section = self._section_block(
|
||||||
|
title='Role Documentation',
|
||||||
|
text='Welcome to the "{}" role documentation.'.format(
|
||||||
|
os.path.basename(role)
|
||||||
|
)
|
||||||
|
)
|
||||||
|
defaults_file = os.path.join(role, 'defaults', 'main.yml')
|
||||||
|
if os.path.exists(defaults_file):
|
||||||
|
with open(defaults_file) as f:
|
||||||
|
role_defaults = DOCYAML.load(f.read())
|
||||||
|
section.append(
|
||||||
|
self._yaml_section(
|
||||||
|
to_yaml_data=role_defaults,
|
||||||
|
section_title='Role Defaults',
|
||||||
|
section_text='This section highlights all of the defaults'
|
||||||
|
' and variables set within the "{}"'
|
||||||
|
' role.'.format(
|
||||||
|
os.path.basename(role)
|
||||||
|
)
|
||||||
|
)
|
||||||
|
)
|
||||||
|
|
||||||
|
vars_path = os.path.join(role, 'vars')
|
||||||
|
if os.path.exists(vars_path):
|
||||||
|
for v_file in os.listdir(vars_path):
|
||||||
|
vars_file = os.path.join(vars_path, v_file)
|
||||||
|
with open(vars_file) as f:
|
||||||
|
vars_values = DOCYAML.load(f.read())
|
||||||
|
section.append(
|
||||||
|
self._yaml_section(
|
||||||
|
to_yaml_data=vars_values,
|
||||||
|
section_title='Role Variables: {}'.format(v_file)
|
||||||
|
)
|
||||||
|
)
|
||||||
|
|
||||||
|
test_list = nodes.field_list()
|
||||||
|
test_section = self._section_block(
|
||||||
|
title='Molecule Scenarios',
|
||||||
|
text='Molecule is being used to test the "{}" role. The'
|
||||||
|
' following section highlights the drivers in service'
|
||||||
|
' and provides an example playbook showing how the role'
|
||||||
|
' is leveraged.'.format(
|
||||||
|
os.path.basename(role)
|
||||||
|
)
|
||||||
|
)
|
||||||
|
molecule_path = os.path.join(role, 'molecule')
|
||||||
|
if os.path.exists(molecule_path):
|
||||||
|
for test in os.listdir(molecule_path):
|
||||||
|
molecule_section = self._section_block(
|
||||||
|
title='Scenario: {}'.format(test)
|
||||||
|
)
|
||||||
|
molecule_file = os.path.join(
|
||||||
|
molecule_path,
|
||||||
|
test,
|
||||||
|
'molecule.yml'
|
||||||
|
)
|
||||||
|
with open(molecule_file) as f:
|
||||||
|
molecule_conf = DOCYAML.load(f.read())
|
||||||
|
|
||||||
|
driver_data = molecule_conf.get('driver')
|
||||||
|
if driver_data:
|
||||||
|
molecule_section.append(
|
||||||
|
nodes.field_name(
|
||||||
|
text='Driver: {}'.format(
|
||||||
|
driver_data['name']
|
||||||
|
)
|
||||||
|
)
|
||||||
|
)
|
||||||
|
|
||||||
|
options = driver_data.get('options')
|
||||||
|
if options:
|
||||||
|
molecule_section.append(
|
||||||
|
self._yaml_section(
|
||||||
|
to_yaml_data=options,
|
||||||
|
section_title='Molecule Options'
|
||||||
|
)
|
||||||
|
)
|
||||||
|
|
||||||
|
provisioner_data = molecule_conf.get('provisioner')
|
||||||
|
if provisioner_data:
|
||||||
|
inventory = provisioner_data.get('inventory')
|
||||||
|
if inventory:
|
||||||
|
molecule_section.append(
|
||||||
|
self._yaml_section(
|
||||||
|
to_yaml_data=inventory,
|
||||||
|
section_title='Molecule Inventory'
|
||||||
|
)
|
||||||
|
)
|
||||||
|
|
||||||
|
molecule_playbook_path = os.path.join(
|
||||||
|
molecule_path,
|
||||||
|
test,
|
||||||
|
'converge.yml'
|
||||||
|
)
|
||||||
|
if not os.path.exists(molecule_playbook_path):
|
||||||
|
molecule_playbook_path = os.path.join(
|
||||||
|
molecule_path,
|
||||||
|
test,
|
||||||
|
'playbook.yml'
|
||||||
|
)
|
||||||
|
with open(molecule_playbook_path) as f:
|
||||||
|
molecule_playbook = DOCYAML.load(f.read())
|
||||||
|
molecule_section.append(
|
||||||
|
self._yaml_section(
|
||||||
|
to_yaml_data=molecule_playbook,
|
||||||
|
section_title='Example {} playbook'.format(test)
|
||||||
|
)
|
||||||
|
)
|
||||||
|
test_list.append(molecule_section)
|
||||||
|
else:
|
||||||
|
test_section.append(test_list)
|
||||||
|
section.append(test_section)
|
||||||
|
|
||||||
|
self.run_returns.append(section)
|
||||||
|
|
||||||
|
# Document any libraries nested within the role
|
||||||
|
library_path = os.path.join(role, 'library')
|
||||||
|
if os.path.exists(library_path):
|
||||||
|
self.options['documentation'] = True
|
||||||
|
self.options['examples'] = True
|
||||||
|
for lib in os.listdir(library_path):
|
||||||
|
if lib.endswith('.py'):
|
||||||
|
self._run_module(
|
||||||
|
module=self.load_module(
|
||||||
|
filename=os.path.join(
|
||||||
|
library_path,
|
||||||
|
lib
|
||||||
|
)
|
||||||
|
),
|
||||||
|
module_title='Embedded module: {}'.format(lib),
|
||||||
|
example_title='Examples for embedded module'
|
||||||
|
)
|
||||||
|
|
||||||
|
def _run_module(self, module, module_title="Module Documentation",
|
||||||
|
example_title="Example Tasks"):
|
||||||
|
if self.options.get('documentation'):
|
||||||
|
docs = self.build_documentation(module=module)
|
||||||
|
self.run_returns.append(
|
||||||
|
self.make_node(
|
||||||
|
title=module_title,
|
||||||
|
contents=docs
|
||||||
|
)
|
||||||
|
)
|
||||||
|
|
||||||
|
if self.options.get('examples'):
|
||||||
|
examples = self.build_examples(module=module)
|
||||||
|
self.run_returns.append(
|
||||||
|
self.make_node(
|
||||||
|
title=example_title,
|
||||||
|
contents=examples,
|
||||||
|
content_type='yaml'
|
||||||
|
)
|
||||||
|
)
|
||||||
|
|
||||||
|
def run(self):
|
||||||
|
self.run_returns = list()
|
||||||
|
|
||||||
|
if self.options.get('module'):
|
||||||
|
module = self.load_module(filename=self.options['module'])
|
||||||
|
self._run_module(module=module)
|
||||||
|
|
||||||
|
if self.options.get('role'):
|
||||||
|
self._run_role(role=self.options['role'])
|
||||||
|
|
||||||
|
return self.run_returns
|
||||||
|
|
||||||
|
|
||||||
|
def setup(app):
|
||||||
|
classes = [
|
||||||
|
AnsibleAutoPluginDirective,
|
||||||
|
]
|
||||||
|
for directive_class in classes:
|
||||||
|
app.add_directive(directive_class.directive_name, directive_class)
|
||||||
|
|
||||||
|
return {'version': '0.2'}
|
@ -1,11 +1,37 @@
|
|||||||
|
#!/usr/bin/env python
|
||||||
|
# -*- coding: utf-8 -*-
|
||||||
|
# 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.
|
||||||
|
|
||||||
|
import os
|
||||||
|
import sys
|
||||||
|
|
||||||
|
# Add the project
|
||||||
|
sys.path.insert(0, os.path.abspath('../..'))
|
||||||
|
# Add the extensions
|
||||||
|
sys.path.insert(0, os.path.join(os.path.abspath('.'), '_exts'))
|
||||||
|
|
||||||
# -- General configuration ----------------------------------------------------
|
# -- General configuration ----------------------------------------------------
|
||||||
|
|
||||||
# Add any Sphinx extension module names here, as strings. They can be
|
# Add any Sphinx extension module names here, as strings. They can be
|
||||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
|
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
|
||||||
extensions = ['sphinxcontrib.apidoc',
|
extensions = [
|
||||||
'sphinx.ext.viewcode',
|
'sphinxcontrib.apidoc',
|
||||||
'openstackdocstheme',
|
'sphinx.ext.viewcode',
|
||||||
]
|
'sphinx.ext.autodoc',
|
||||||
|
'openstackdocstheme',
|
||||||
|
'ansible-autodoc'
|
||||||
|
]
|
||||||
|
|
||||||
# sphinxcontrib.apidoc options
|
# sphinxcontrib.apidoc options
|
||||||
apidoc_module_dir = '../../validations_libs'
|
apidoc_module_dir = '../../validations_libs'
|
||||||
@ -16,8 +42,9 @@ apidoc_separate_modules = True
|
|||||||
|
|
||||||
# openstackdocstheme options
|
# openstackdocstheme options
|
||||||
openstackdocs_repo_name = 'openstack/validations-libs'
|
openstackdocs_repo_name = 'openstack/validations-libs'
|
||||||
openstackdocs_pdf_link = True
|
|
||||||
openstackdocs_use_storyboard = True
|
openstackdocs_use_storyboard = True
|
||||||
|
openstackdocs_bug_project = 'tripleo'
|
||||||
|
openstackdocs_bug_tag = 'documentation'
|
||||||
|
|
||||||
# autodoc generation is a bit aggressive and a nuisance when doing heavy
|
# autodoc generation is a bit aggressive and a nuisance when doing heavy
|
||||||
# text edit cycles.
|
# text edit cycles.
|
||||||
@ -33,7 +60,7 @@ source_suffix = '.rst'
|
|||||||
master_doc = 'index'
|
master_doc = 'index'
|
||||||
|
|
||||||
# General information about the project.
|
# General information about the project.
|
||||||
copyright = u'OpenStack Foundation'
|
copyright = u'2021, OpenStack Foundation'
|
||||||
|
|
||||||
# A list of ignored prefixes for module index sorting.
|
# A list of ignored prefixes for module index sorting.
|
||||||
modindex_common_prefix = ['validations_libs.']
|
modindex_common_prefix = ['validations_libs.']
|
||||||
|
@ -4,8 +4,7 @@
|
|||||||
Contributing to validations-libs
|
Contributing to validations-libs
|
||||||
================================
|
================================
|
||||||
|
|
||||||
If you're interested in contributing to the validations-libs project,
|
.. include:: ../../CONTRIBUTING.rst
|
||||||
the following will help get you started.
|
|
||||||
|
|
||||||
#tripleo on Freenode IRC Network
|
#tripleo on Freenode IRC Network
|
||||||
--------------------------------
|
--------------------------------
|
||||||
@ -38,3 +37,4 @@ Code Hosting
|
|||||||
|
|
||||||
Code Review
|
Code Review
|
||||||
https://review.opendev.org/#/q/status:open+project:openstack/validations-libs,n,z
|
https://review.opendev.org/#/q/status:open+project:openstack/validations-libs,n,z
|
||||||
|
|
@ -1,8 +0,0 @@
|
|||||||
==========================================
|
|
||||||
validations-libs Contributor Documentation
|
|
||||||
==========================================
|
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
|
|
||||||
contributing
|
|
||||||
testing
|
|
@ -13,12 +13,13 @@ Contents
|
|||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
|
|
||||||
contributor/index
|
readme
|
||||||
|
contributing
|
||||||
|
testing
|
||||||
reference/index
|
reference/index
|
||||||
|
|
||||||
Indices and tables
|
Indices and tables
|
||||||
==================
|
==================
|
||||||
|
|
||||||
* :ref:`genindex`
|
* :ref:`genindex`
|
||||||
* :ref:`modindex`
|
|
||||||
* :ref:`search`
|
* :ref:`search`
|
||||||
|
1
doc/source/readme.rst
Normal file
1
doc/source/readme.rst
Normal file
@ -0,0 +1 @@
|
|||||||
|
.. include:: ../../README.rst
|
0
releasenotes/notes/.gitkeep
Normal file
0
releasenotes/notes/.gitkeep
Normal file
0
releasenotes/source/_static/.gitkeep
Normal file
0
releasenotes/source/_static/.gitkeep
Normal file
321
releasenotes/source/conf.py
Normal file
321
releasenotes/source/conf.py
Normal file
@ -0,0 +1,321 @@
|
|||||||
|
# -*- coding: utf-8 -*-
|
||||||
|
# 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.
|
||||||
|
#
|
||||||
|
# flake8: noqa
|
||||||
|
|
||||||
|
# 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
|
||||||
|
# sys.path.insert(0, os.path.abspath('.'))
|
||||||
|
|
||||||
|
# -- General configuration ------------------------------------------------
|
||||||
|
|
||||||
|
# If your documentation needs a minimal Sphinx version, state it here.
|
||||||
|
#
|
||||||
|
# needs_sphinx = '1.0'
|
||||||
|
|
||||||
|
# Add any Sphinx extension module names here, as strings. They can be
|
||||||
|
# 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']
|
||||||
|
|
||||||
|
# The suffix(es) of source filenames.
|
||||||
|
# You can specify multiple suffix as a list of string:
|
||||||
|
#
|
||||||
|
# source_suffix = ['.rst', '.md']
|
||||||
|
source_suffix = '.rst'
|
||||||
|
|
||||||
|
# The encoding of source files.
|
||||||
|
#
|
||||||
|
# source_encoding = 'utf-8-sig'
|
||||||
|
|
||||||
|
# The master toctree document.
|
||||||
|
master_doc = 'index'
|
||||||
|
|
||||||
|
# General information about the project.
|
||||||
|
authors = u'Validations Framework Developers'
|
||||||
|
project = u'validations-libs Release Notes'
|
||||||
|
copyright = u'2021, ' + authors
|
||||||
|
|
||||||
|
# The language for content autogenerated by Sphinx. Refer to documentation
|
||||||
|
# for a list of supported languages.
|
||||||
|
#
|
||||||
|
# This is also used if you do content translation via gettext catalogs.
|
||||||
|
# Usually you set "language" from the command line for these cases.
|
||||||
|
# language = None
|
||||||
|
|
||||||
|
# There are two options for replacing |today|: either, you set today to some
|
||||||
|
# non-false value, then it is used:
|
||||||
|
#
|
||||||
|
# today = ''
|
||||||
|
#
|
||||||
|
# Else, today_fmt is used as the format for a strftime call.
|
||||||
|
#
|
||||||
|
# today_fmt = '%B %d, %Y'
|
||||||
|
|
||||||
|
# List of patterns, relative to source directory, that match files and
|
||||||
|
# directories to ignore when looking for source files.
|
||||||
|
# This patterns also effect to html_static_path and html_extra_path
|
||||||
|
exclude_patterns = []
|
||||||
|
|
||||||
|
# The reST default role (used for this markup: `text`) to use for all
|
||||||
|
# documents.
|
||||||
|
#
|
||||||
|
# default_role = None
|
||||||
|
|
||||||
|
# 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
|
||||||
|
|
||||||
|
# If true, sectionauthor and moduleauthor directives will be shown in the
|
||||||
|
# output. They are ignored by default.
|
||||||
|
#
|
||||||
|
# show_authors = False
|
||||||
|
|
||||||
|
# The name of the Pygments (syntax highlighting) style to use.
|
||||||
|
pygments_style = 'native'
|
||||||
|
|
||||||
|
# A list of ignored prefixes for module index sorting.
|
||||||
|
# modindex_common_prefix = []
|
||||||
|
|
||||||
|
# If true, keep warnings as "system message" paragraphs in the built documents.
|
||||||
|
# keep_warnings = False
|
||||||
|
|
||||||
|
# If true, `todo` and `todoList` produce output, else they produce nothing.
|
||||||
|
# todo_include_todos = False
|
||||||
|
|
||||||
|
|
||||||
|
# -- 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 = 'openstackdocs'
|
||||||
|
|
||||||
|
# Theme options are theme-specific and customize the look and feel of a theme
|
||||||
|
# further. For a list of options available for each theme, see the
|
||||||
|
# documentation.
|
||||||
|
#
|
||||||
|
# html_theme_options = {}
|
||||||
|
|
||||||
|
# Add any paths that contain custom themes here, relative to this directory.
|
||||||
|
#html_theme_path = []
|
||||||
|
|
||||||
|
# The name for this set of Sphinx documents.
|
||||||
|
# "<project> v<release> documentation" by default.
|
||||||
|
#
|
||||||
|
# html_title = u'validations-libs v1.0'
|
||||||
|
|
||||||
|
# A shorter title for the navigation bar. Default is the same as html_title.
|
||||||
|
#
|
||||||
|
# html_short_title = None
|
||||||
|
|
||||||
|
# The name of an image file (relative to this directory) to place at the top
|
||||||
|
# of the sidebar.
|
||||||
|
#
|
||||||
|
# html_logo = None
|
||||||
|
|
||||||
|
# The name of an image file (relative to this directory) to use as a favicon of
|
||||||
|
# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
|
||||||
|
# pixels large.
|
||||||
|
#
|
||||||
|
# html_favicon = None
|
||||||
|
|
||||||
|
# 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']
|
||||||
|
|
||||||
|
# Add any extra paths that contain custom files (such as robots.txt or
|
||||||
|
# .htaccess) here, relative to this directory. These files are copied
|
||||||
|
# directly to the root of the documentation.
|
||||||
|
#
|
||||||
|
# html_extra_path = []
|
||||||
|
|
||||||
|
# If true, SmartyPants will be used to convert quotes and dashes to
|
||||||
|
# typographically correct entities.
|
||||||
|
#
|
||||||
|
# html_use_smartypants = True
|
||||||
|
|
||||||
|
# Custom sidebar templates, maps document names to template names.
|
||||||
|
#
|
||||||
|
# html_sidebars = {}
|
||||||
|
|
||||||
|
# Additional templates that should be rendered to pages, maps page names to
|
||||||
|
# template names.
|
||||||
|
#
|
||||||
|
# html_additional_pages = {}
|
||||||
|
|
||||||
|
# If false, no module index is generated.
|
||||||
|
#
|
||||||
|
# html_domain_indices = True
|
||||||
|
|
||||||
|
# If false, no index is generated.
|
||||||
|
#html_use_index = True
|
||||||
|
|
||||||
|
# If true, the index is split into individual pages for each letter.
|
||||||
|
#
|
||||||
|
# html_split_index = False
|
||||||
|
|
||||||
|
# If true, links to the reST sources are added to the pages.
|
||||||
|
#
|
||||||
|
# html_show_sourcelink = True
|
||||||
|
|
||||||
|
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
|
||||||
|
#
|
||||||
|
# html_show_sphinx = True
|
||||||
|
|
||||||
|
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
|
||||||
|
#
|
||||||
|
# html_show_copyright = True
|
||||||
|
|
||||||
|
# If true, an OpenSearch description file will be output, and all pages will
|
||||||
|
# contain a <link> tag referring to it. The value of this option must be the
|
||||||
|
# base URL from which the finished HTML is served.
|
||||||
|
#
|
||||||
|
# html_use_opensearch = ''
|
||||||
|
|
||||||
|
# This is the file name suffix for HTML files (e.g. ".xhtml").
|
||||||
|
# html_file_suffix = None
|
||||||
|
|
||||||
|
# Language to be used for generating the HTML full-text search index.
|
||||||
|
# Sphinx supports the following languages:
|
||||||
|
# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
|
||||||
|
# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
|
||||||
|
#
|
||||||
|
# html_search_language = 'en'
|
||||||
|
|
||||||
|
# A dictionary with options for the search language support, empty by default.
|
||||||
|
# 'ja' uses this config value.
|
||||||
|
# 'zh' user can custom change `jieba` dictionary path.
|
||||||
|
#
|
||||||
|
# html_search_options = {'type': 'default'}
|
||||||
|
|
||||||
|
# The name of a javascript file (relative to the configuration directory) that
|
||||||
|
# implements a search results scorer. If empty, the default will be used.
|
||||||
|
#
|
||||||
|
# html_search_scorer = 'scorer.js'
|
||||||
|
|
||||||
|
# Output file base name for HTML help builder.
|
||||||
|
htmlhelp_basename = 'validations-libsReleaseNotesdoc'
|
||||||
|
|
||||||
|
# -- Options for LaTeX output ---------------------------------------------
|
||||||
|
|
||||||
|
# Grouping the document tree into LaTeX files. List of tuples
|
||||||
|
# (source start file, target name, title,
|
||||||
|
# author, documentclass [howto, manual, or own class]).
|
||||||
|
latex_documents = [
|
||||||
|
(master_doc, 'validations-libsReleaseNotes.tex',
|
||||||
|
u'validations-libs Release Notes Documentation',
|
||||||
|
authors, 'manual'),
|
||||||
|
]
|
||||||
|
|
||||||
|
# The name of an image file (relative to this directory) to place at the top of
|
||||||
|
# the title page.
|
||||||
|
#
|
||||||
|
# latex_logo = None
|
||||||
|
|
||||||
|
# For "manual" documents, if this is true, then toplevel headings are parts,
|
||||||
|
# not chapters.
|
||||||
|
#
|
||||||
|
# latex_use_parts = False
|
||||||
|
|
||||||
|
# If true, show page references after internal links.
|
||||||
|
#
|
||||||
|
# latex_show_pagerefs = False
|
||||||
|
|
||||||
|
# If true, show URL addresses after external links.
|
||||||
|
#
|
||||||
|
# latex_show_urls = False
|
||||||
|
|
||||||
|
# Documents to append as an appendix to all manuals.
|
||||||
|
#
|
||||||
|
# latex_appendices = []
|
||||||
|
|
||||||
|
# It false, will not define \strong, \code, itleref, \crossref ... but only
|
||||||
|
# \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added
|
||||||
|
# packages.
|
||||||
|
#
|
||||||
|
# latex_keep_old_macro_names = True
|
||||||
|
|
||||||
|
# If false, no module index is generated.
|
||||||
|
#
|
||||||
|
# latex_domain_indices = True
|
||||||
|
|
||||||
|
|
||||||
|
# -- Options for manual page output ---------------------------------------
|
||||||
|
|
||||||
|
# One entry per manual page. List of tuples
|
||||||
|
# (source start file, name, description, authors, manual section).
|
||||||
|
man_pages = [
|
||||||
|
(master_doc, 'validations-libsreleasenotes',
|
||||||
|
u'validations-libs Release Notes Documentation',
|
||||||
|
[authors], 1)
|
||||||
|
]
|
||||||
|
|
||||||
|
# If true, show URL addresses after external links.
|
||||||
|
#
|
||||||
|
# man_show_urls = False
|
||||||
|
|
||||||
|
|
||||||
|
# -- Options for Texinfo output -------------------------------------------
|
||||||
|
|
||||||
|
# Grouping the document tree into Texinfo files. List of tuples
|
||||||
|
# (source start file, target name, title, author,
|
||||||
|
# dir menu entry, description, category)
|
||||||
|
texinfo_documents = [
|
||||||
|
(master_doc, 'validations-libsReleaseNotes',
|
||||||
|
u'validations-libs Release Notes Documentation',
|
||||||
|
authors, 'validations-libsReleaseNotes',
|
||||||
|
'A collection of python libraries for the Validation Framework.',
|
||||||
|
'Miscellaneous'),
|
||||||
|
]
|
||||||
|
|
||||||
|
# Documents to append as an appendix to all manuals.
|
||||||
|
#
|
||||||
|
# texinfo_appendices = []
|
||||||
|
|
||||||
|
# If false, no module index is generated.
|
||||||
|
#
|
||||||
|
# texinfo_domain_indices = True
|
||||||
|
|
||||||
|
# How to display URL addresses: 'footnote', 'no', or 'inline'.
|
||||||
|
#
|
||||||
|
# texinfo_show_urls = 'footnote'
|
||||||
|
|
||||||
|
# If true, do not generate a @detailmenu in the "Top" node's menu.
|
||||||
|
#
|
||||||
|
# texinfo_no_detailmenu = False
|
||||||
|
|
||||||
|
# -- Options for Internationalization output ------------------------------
|
||||||
|
locale_dirs = ['locale/']
|
||||||
|
|
||||||
|
# openstackdocstheme options
|
||||||
|
repository_name = 'openstack/validations-libs'
|
||||||
|
bug_project = 'tripleo'
|
||||||
|
bug_tag = 'documentation'
|
18
releasenotes/source/index.rst
Normal file
18
releasenotes/source/index.rst
Normal file
@ -0,0 +1,18 @@
|
|||||||
|
=============================================
|
||||||
|
Welcome to validations-libs' Release Notes!
|
||||||
|
=============================================
|
||||||
|
|
||||||
|
Contents
|
||||||
|
========
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 2
|
||||||
|
|
||||||
|
unreleased
|
||||||
|
ussuri
|
||||||
|
|
||||||
|
Indices and tables
|
||||||
|
==================
|
||||||
|
|
||||||
|
* :ref:`genindex`
|
||||||
|
* :ref:`search`
|
5
releasenotes/source/unreleased.rst
Normal file
5
releasenotes/source/unreleased.rst
Normal file
@ -0,0 +1,5 @@
|
|||||||
|
==============================
|
||||||
|
Current Series Release Notes
|
||||||
|
==============================
|
||||||
|
|
||||||
|
.. release-notes::
|
6
releasenotes/source/ussuri.rst
Normal file
6
releasenotes/source/ussuri.rst
Normal file
@ -0,0 +1,6 @@
|
|||||||
|
===========================
|
||||||
|
Ussuri Series Release Notes
|
||||||
|
===========================
|
||||||
|
|
||||||
|
.. release-notes::
|
||||||
|
:branch: stable/ussuri
|
@ -1,11 +1,11 @@
|
|||||||
[metadata]
|
[metadata]
|
||||||
name = validations-libs
|
name = validations-libs
|
||||||
summary = A common library for the validations framework
|
summary = A common library for the validations framework
|
||||||
description-file =
|
long_description = file:README.rst
|
||||||
README.rst
|
long_description_content_type = text/x-rst
|
||||||
author = OpenStack
|
author = OpenStack
|
||||||
author-email = openstack-discuss@lists.openstack.org
|
author-email = openstack-discuss@lists.openstack.org
|
||||||
home-page = https://docs.openstack.org/tripleo-validations/latest/
|
home-page = https://docs.openstack.org/validations-libs/latest/
|
||||||
classifier =
|
classifier =
|
||||||
Environment :: OpenStack
|
Environment :: OpenStack
|
||||||
Intended Audience :: Information Technology
|
Intended Audience :: Information Technology
|
||||||
|
21
tox.ini
21
tox.ini
@ -28,6 +28,7 @@ deps =
|
|||||||
-c {env:TOX_CONSTRAINTS_FILE:https://opendev.org/openstack/requirements/raw/branch/master/upper-constraints.txt}
|
-c {env:TOX_CONSTRAINTS_FILE:https://opendev.org/openstack/requirements/raw/branch/master/upper-constraints.txt}
|
||||||
-r {toxinidir}/requirements.txt
|
-r {toxinidir}/requirements.txt
|
||||||
-r {toxinidir}/test-requirements.txt
|
-r {toxinidir}/test-requirements.txt
|
||||||
|
-r {toxinidir}/doc/requirements.txt
|
||||||
whitelist_externals = bash
|
whitelist_externals = bash
|
||||||
|
|
||||||
[testenv:bindep]
|
[testenv:bindep]
|
||||||
@ -66,6 +67,11 @@ commands =
|
|||||||
{[testenv:whitespace]commands}
|
{[testenv:whitespace]commands}
|
||||||
{[testenv:shebangs]commands}
|
{[testenv:shebangs]commands}
|
||||||
|
|
||||||
|
[testenv:releasenotes]
|
||||||
|
deps = -r {toxinidir}/doc/requirements.txt
|
||||||
|
commands =
|
||||||
|
sphinx-build -a -E -W -d releasenotes/build/doctrees --keep-going -b html releasenotes/source releasenotes/build/html
|
||||||
|
|
||||||
[testenv:venv]
|
[testenv:venv]
|
||||||
commands = {posargs}
|
commands = {posargs}
|
||||||
passenv = *
|
passenv = *
|
||||||
@ -88,15 +94,16 @@ deps =
|
|||||||
-r {toxinidir}/test-requirements.txt
|
-r {toxinidir}/test-requirements.txt
|
||||||
-r {toxinidir}/doc/requirements.txt
|
-r {toxinidir}/doc/requirements.txt
|
||||||
commands=
|
commands=
|
||||||
sphinx-build -W -b html doc/source doc/build/html
|
sphinx-build -a -E -W -d doc/build/doctrees --keep-going -b html doc/source doc/build/html -T
|
||||||
doc8 doc
|
doc8 doc
|
||||||
|
|
||||||
[testenv:pdf-docs]
|
#TODO(jpodivin): pdf-docs don't compile properly
|
||||||
whitelist_externals = make
|
; [testenv:pdf-docs]
|
||||||
deps = {[testenv:docs]deps}
|
; whitelist_externals = make
|
||||||
commands =
|
; deps = {[testenv:docs]deps}
|
||||||
sphinx-build -W -b latex doc/source doc/build/pdf
|
; commands =
|
||||||
make -C doc/build/pdf
|
; sphinx-build -W -b latex doc/source doc/build/pdf
|
||||||
|
; make -C doc/build/pdf
|
||||||
|
|
||||||
[doc8]
|
[doc8]
|
||||||
# Settings for doc8:
|
# Settings for doc8:
|
||||||
|
Loading…
Reference in New Issue
Block a user