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
http://lists.openstack.org/pipermail/openstack-dev/2017-December/125710.html

Remove the '[build_sphinx]' and [pbr] sections as described in:
http://lists.openstack.org/pipermail/openstack-dev/2018-March/128594.html

Adds the use of sphinxcontrib.apidoc to get (mostly) the same output as what
was provided by the removed [pbr] section.

Change-Id: Ie7e3acef7161cb8f218c2333167490c8116a2122
Depends-On: https://review.openstack.org/#/c/560270/
This commit is contained in:
Nguyen Hai 2018-03-22 17:23:30 +09:00
parent ec3e9dbb32
commit 5e5ba92aec
7 changed files with 33 additions and 43 deletions

11
doc/requirements.txt Normal file
View File

@ -0,0 +1,11 @@
# 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.
sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
os-api-ref>=1.4.0 # Apache-2.0
openstackdocstheme>=1.18.1 # Apache-2.0
reno>=2.5.0 # Apache-2.0
sphinxcontrib-apidoc>=0.2.0 # BSD
# needed for apidoc support
xattr>=0.9.2

View File

@ -48,11 +48,11 @@ sys.path = [
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['stevedore.sphinxext',
'sphinx.ext.autodoc',
'sphinx.ext.viewcode',
'oslo_config.sphinxext',
'oslo_config.sphinxconfiggen',
'openstackdocstheme',
'sphinxcontrib.apidoc',
]
# openstackdocstheme options
@ -61,6 +61,16 @@ bug_project = 'glance'
bug_tag = ''
html_last_updated_fmt = '%Y-%m-%d %H:%M'
# sphinxcontrib.apidoc options
apidoc_module_dir = '../../glance'
apidoc_output_dir = 'contributor/api'
apidoc_excluded_paths = [
'tests/*',
'tests',
'db/sqlalchemy/*',
'db/sqlalchemy']
apidoc_separate_modules = True
config_generator_config_file = [
('../../etc/oslo-config-generator/glance-api.conf',
'_static/glance-api'),

View File

@ -42,10 +42,8 @@ Developer Reference
database_architecture
domain_model
domain_implementation
.. toctree::
:maxdepth: 1
modules
Module Reference <api/modules>
Development Roles
-----------------

View File

@ -1,20 +0,0 @@
..
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.
Module Reference
================
.. toctree::
:maxdepth: 1
api/autoindex

View File

@ -79,12 +79,6 @@ glance.image_import.plugins =
glance.image_import.internal_plugins =
web_download = glance.async.flows._internal_plugins.web_download:get_flow
[build_sphinx]
builder = html man
all_files = 1
build-dir = doc/build
source-dir = doc/source
warning-is-error = 1
[egg_info]
tag_build =
@ -104,10 +98,3 @@ input_file = glance/locale/glance.pot
keywords = _ gettext ngettext l_ lazy_gettext
mapping_file = babel.cfg
output_file = glance/locale/glance.pot
[pbr]
autodoc_index_modules = True
autodoc_exclude_modules =
glance.tests.*
glance.db.sqlalchemy.*
api_doc_dir = contributor/api

View File

@ -32,8 +32,3 @@ pysendfile>=2.0.0 # MIT
qpid-python>=0.26;python_version=='2.7' # Apache-2.0
xattr>=0.9.2 # MIT
python-swiftclient>=3.2.0 # Apache-2.0
# Documentation
os-api-ref>=1.4.0 # Apache-2.0
openstackdocstheme>=1.18.1 # Apache-2.0
reno>=2.5.0 # Apache-2.0

11
tox.ini
View File

@ -69,6 +69,9 @@ commands =
[testenv:api-ref]
# This environment is called from CI scripts to test and publish
# the API Ref to developer.openstack.org.
deps =
-c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt}
-r{toxinidir}/doc/requirements.txt
commands =
rm -rf api-ref/build
sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
@ -101,9 +104,12 @@ local-check-factory = glance.hacking.checks.factory
import_exceptions = glance.i18n
[testenv:docs]
deps =
-c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt}
-r{toxinidir}/doc/requirements.txt
commands =
rm -fr doc/build
python setup.py build_sphinx
sphinx-build -W -b html doc/source doc/build/html
[testenv:venv]
commands = {posargs}
@ -112,6 +118,9 @@ commands = {posargs}
commands = bandit -c bandit.yaml -r glance -n5 -p gate
[testenv:releasenotes]
deps =
-c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/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