Follow the new PTI for document build

For compliance with the Project Testing Interface as described in:

https://governance.openstack.org/tc/reference/project-testing-interface.html

For more detailed information, please refer to:

http://lists.openstack.org/pipermail/openstack-dev/2017-December/125710.html

Change-Id: Id20646cd51ffc13cf4e77c640eb677fe376c1b1f
Co-Authored-By: Stephen Finucane <stephenfin@redhat.com>
This commit is contained in:
ZhongShengping 2018-03-02 10:29:12 +08:00 committed by Stephen Finucane
parent f1c25b189f
commit c59246530f
8 changed files with 38 additions and 91 deletions

2
.gitignore vendored
View File

@ -57,3 +57,5 @@ ChangeLog
# reno build
releasenotes/build
/doc/source/reference/api/
releasenotes/notes/reno.cache
RELEASENOTES.rst

10
doc/requirements.txt Normal file
View File

@ -0,0 +1,10 @@
# 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.
# These are needed for docs generation
openstackdocstheme>=1.20.0 # Apache-2.0
sphinx!=1.6.6,!=1.6.7,>=1.6.2,<2.0.0;python_version=='2.7' # BSD
sphinx!=1.6.6,!=1.6.7,>=1.6.2;python_version>='3.4' # BSD
reno>=2.5.0 # Apache-2.0
fixtures>=3.0.0 # Apache-2.0/BSD
sphinxcontrib-apidoc>=0.2.0 # BSD

View File

@ -11,20 +11,14 @@
# See the License for the specific language governing permissions and
# limitations under the License.
import os
import sys
import fileinput
import fnmatch
sys.path.insert(0, os.path.abspath('../..'))
# -- 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.intersphinx',
'openstackdocstheme'
'sphinxcontrib.apidoc',
'openstackdocstheme',
]
# openstackdocstheme options
@ -32,31 +26,6 @@ repository_name = 'openstack/oslo.vmware'
bug_project = 'oslo.vmware'
bug_tag = ''
# 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
# A list of glob-style patterns that should be excluded when looking for source
# files.
exclude_patterns = [
'api/tests.*', # avoid of docs generation from tests
'api/oslo.vmware._*', # skip private modules
]
# Prune the excluded patterns from the autoindex
PATH = 'api/autoindex.rst'
if os.path.isfile(PATH) and os.access(PATH, os.R_OK):
for line in fileinput.input(PATH, inplace=True):
found = False
for pattern in exclude_patterns:
if fnmatch.fnmatch(line, '*' + pattern[4:]):
found = True
if not found:
print(line)
# The suffix of source filenames.
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
@ -74,29 +43,16 @@ add_module_names = True
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# -- 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'
html_last_updated_fmt = '%Y-%m-%d %H:%M'
# Output file base name for HTML help builder.
htmlhelp_basename = '%sdoc' % project
# -- sphinxcontrib.apidoc configuration --------------------------------------
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass
# [howto/manual]).
latex_documents = [
('index',
'%s.tex' % project,
u'%s Documentation' % project,
u'OpenStack Foundation', 'manual'),
apidoc_module_dir = '../../oslo_vmware'
apidoc_output_dir = 'reference/api'
apidoc_excluded_paths = [
'tests',
]
# Example configuration for intersphinx: refer to the Python standard library.
#intersphinx_mapping = {'http://docs.python.org/': None}

View File

@ -6,4 +6,4 @@ API Reference
:maxdepth: 1
:glob:
api/autoindex
api/modules

View File

@ -26,7 +26,7 @@ mock==2.0.0
monotonic==0.6
netaddr==0.7.18
netifaces==0.10.4
openstackdocstheme==1.18.1
openstackdocstheme==1.20.0
oslo.concurrency==3.26.0
oslo.config==5.2.0
oslo.context==2.19.2

View File

@ -23,15 +23,6 @@ classifier =
packages =
oslo_vmware
[build_sphinx]
source-dir = doc/source
build-dir = doc/build
all_files = 1
warning-is-error = 1
[upload_sphinx]
upload-dir = doc/build/html
[compile_catalog]
directory = oslo_vmware/locale
domain = oslo_vmware
@ -46,12 +37,5 @@ keywords = _ gettext ngettext l_ lazy_gettext
mapping_file = babel.cfg
output_file = oslo_vmware/locale/oslo_vmware.pot
[pbr]
autodoc_index_modules = 1
autodoc_exclude_modules =
oslo_vmware._i18n
oslo_vmware.tests.*
api_doc_dir = reference/api
[wheel]
universal = 1

View File

@ -14,13 +14,6 @@ stestr>=2.0.0 # Apache-2.0
# [testenv:cover]
# deps = {[testenv]deps} coverage
coverage!=4.4,>=4.0 # Apache-2.0
# this is required for the docs build jobs
openstackdocstheme>=1.18.1 # Apache-2.0
sphinx!=1.6.6,!=1.6.7,>=1.6.2,<2.0.0;python_version=='2.7' # BSD
sphinx!=1.6.6,!=1.6.7,>=1.6.2;python_version>='3.4' # BSD
reno>=2.5.0 # Apache-2.0
bandit>=1.1.0 # Apache-2.0
ddt>=1.0.1 # MIT
oslo.context>=2.19.2 # Apache-2.0

30
tox.ini
View File

@ -4,8 +4,8 @@ envlist = py27,py37,pep8
[testenv]
install_command = pip install {opts} {packages}
whitelist_externals = find
rm
whitelist_externals =
find
deps =
-c{env:UPPER_CONSTRAINTS_FILE:https://opendev.org/openstack/requirements/raw/branch/master/upper-constraints.txt}
-r{toxinidir}/test-requirements.txt
@ -19,22 +19,20 @@ commands =
# Run security linter
bandit -r oslo_vmware
[testenv:pylint]
basepython = python3
deps =
-c{env:UPPER_CONSTRAINTS_FILE:https://opendev.org/openstack/requirements/raw/branch/master/upper-constraints.txt}
-r{toxinidir}/test-requirements.txt
-r{toxinidir}/requirements.txt
pylint>=1.3.0
commands = pylint oslo
[testenv:bandit]
basepython = python3
commands = bandit -r oslo_vmware
[testenv:docs]
basepython = python3
commands = python setup.py build_sphinx
whitelist_externals =
rm
deps =
{[testenv]deps}
-r{toxinidir}/doc/requirements.txt
commands =
rm -rf doc/build doc/source/reference/api
sphinx-build -W -b html doc/source doc/build/html
[testenv:cover]
basepython = python3
@ -54,12 +52,16 @@ ignore = H405
exclude=.venv,.git,.tox,dist,doc,*lib/python*,*egg,build,__init__.py
[hacking]
import_exceptions = oslo_vmware.tests.base
tests.base
import_exceptions =
oslo_vmware.tests.base
tests.base
local-check-factory = oslo_vmware.hacking.checks.factory
[testenv:releasenotes]
basepython = python3
deps =
-c{env:UPPER_CONSTRAINTS_FILE:https://opendev.org/openstack/requirements/raw/branch/master/upper-constraints.txt}
-r{toxinidir}/doc/requirements.txt
commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
[testenv:bindep]