From c59246530f418fa21b9e0d383a123560f11c839c Mon Sep 17 00:00:00 2001 From: ZhongShengping Date: Fri, 2 Mar 2018 10:29:12 +0800 Subject: [PATCH] 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 --- .gitignore | 2 ++ doc/requirements.txt | 10 ++++++ doc/source/conf.py | 60 +++++----------------------------- doc/source/reference/index.rst | 2 +- lower-constraints.txt | 2 +- setup.cfg | 16 --------- test-requirements.txt | 7 ---- tox.ini | 30 +++++++++-------- 8 files changed, 38 insertions(+), 91 deletions(-) create mode 100644 doc/requirements.txt diff --git a/.gitignore b/.gitignore index f0f970ac..f9af03cd 100644 --- a/.gitignore +++ b/.gitignore @@ -57,3 +57,5 @@ ChangeLog # reno build releasenotes/build /doc/source/reference/api/ +releasenotes/notes/reno.cache +RELEASENOTES.rst diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 00000000..758afce8 --- /dev/null +++ b/doc/requirements.txt @@ -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 diff --git a/doc/source/conf.py b/doc/source/conf.py index f696d32f..8cece1b1 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -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} diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst index 87370d43..b2f79451 100644 --- a/doc/source/reference/index.rst +++ b/doc/source/reference/index.rst @@ -6,4 +6,4 @@ API Reference :maxdepth: 1 :glob: - api/autoindex + api/modules diff --git a/lower-constraints.txt b/lower-constraints.txt index c4088ea7..42001652 100644 --- a/lower-constraints.txt +++ b/lower-constraints.txt @@ -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 diff --git a/setup.cfg b/setup.cfg index aee2cd2a..ef6dcebf 100644 --- a/setup.cfg +++ b/setup.cfg @@ -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 diff --git a/test-requirements.txt b/test-requirements.txt index 091b83b5..c4f7f31d 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -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 diff --git a/tox.ini b/tox.ini index 1c2edb3f..3926707c 100644 --- a/tox.ini +++ b/tox.ini @@ -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]