docs: Use sphinxcontrib.apidoc for building API docs
Gets us away from the old pbr functionality. Some cleanup of tox.ini is included along the way. Change-Id: Ia228f8ee49f31f88fa2a66f2aad3a3921c41a785
This commit is contained in:
Stephen Finucane
parent
b9c51e295b
commit
05ddd9fc9e
|
|
@ -6,9 +6,4 @@ 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
|
||||
doc8>=0.6.0 # Apache-2.0
|
||||
reno>=2.5.0 # Apache-2.0
|
||||
|
||||
# These modules are needed when generating document
|
||||
fixtures>=3.0.0 # Apache-2.0/BSD
|
||||
testresources>=2.0.0 # Apache-2.0/BSD
|
||||
testscenarios>=0.4 # Apache-2.0/BSD
|
||||
oslotest>=3.2.0 # Apache-2.0
|
||||
sphinxcontrib-apidoc>=0.2.0 # BSD
|
||||
|
|
|
|||
|
|
@ -11,17 +11,13 @@
|
|||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
|
||||
import os
|
||||
import sys
|
||||
|
||||
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',
|
||||
'sphinxcontrib.apidoc',
|
||||
'oslo_config.sphinxext',
|
||||
'openstackdocstheme',
|
||||
'stevedore.sphinxext'
|
||||
|
|
@ -31,23 +27,6 @@ repository_name = 'openstack/oslo.db'
|
|||
bug_project = 'oslo.db'
|
||||
bug_tag = ''
|
||||
|
||||
# Must set this variable to include year, month, day, hours, and minutes.
|
||||
html_last_updated_fmt = '%Y-%m-%d %H:%M'
|
||||
|
||||
# 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/setup.rst', # workaround for https://launchpad.net/bugs/1260495
|
||||
'api/tests.*', # avoid of docs generation from tests
|
||||
]
|
||||
|
||||
# The suffix of source filenames.
|
||||
source_suffix = '.rst'
|
||||
|
||||
# The master toctree document.
|
||||
master_doc = 'index'
|
||||
|
||||
|
|
@ -68,26 +47,18 @@ pygments_style = 'sphinx'
|
|||
# A list of ignored prefixes for module index sorting.
|
||||
modindex_common_prefix = ['oslo_db.']
|
||||
|
||||
# -- Options for HTML output --------------------------------------------------
|
||||
|
||||
# -- 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 = 'openstackdocs'
|
||||
# html_static_path = ['static']
|
||||
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = '%sdoc' % project
|
||||
|
||||
# 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'),
|
||||
# -- sphinxcontrib.apidoc configuration --------------------------------------
|
||||
|
||||
apidoc_module_dir = '../../oslo_db'
|
||||
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}
|
||||
|
|
|
|||
|
|
@ -15,4 +15,4 @@ API
|
|||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
api/autoindex
|
||||
api/modules
|
||||
|
|
|
|||
19
setup.cfg
19
setup.cfg
|
|
@ -21,10 +21,10 @@ classifier =
|
|||
[extras]
|
||||
# So e.g. nova can test-depend on oslo.db[mysql]
|
||||
mysql =
|
||||
PyMySQL>=0.7.6 # MIT License
|
||||
PyMySQL>=0.7.6 # MIT License
|
||||
# or oslo.db[postgresql]
|
||||
postgresql =
|
||||
psycopg2>=2.7.0 # LGPL/ZPL
|
||||
psycopg2>=2.7.0 # LGPL/ZPL
|
||||
|
||||
[files]
|
||||
packages =
|
||||
|
|
@ -42,15 +42,6 @@ oslo.db.migration =
|
|||
[bdist_wheel]
|
||||
universal = 1
|
||||
|
||||
[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_db/locale
|
||||
domain = oslo_db
|
||||
|
|
@ -64,9 +55,3 @@ input_file = oslo_db/locale/oslo_db.pot
|
|||
keywords = _ gettext ngettext l_ lazy_gettext
|
||||
mapping_file = babel.cfg
|
||||
output_file = oslo_db/locale/oslo_db.pot
|
||||
|
||||
[pbr]
|
||||
autodoc_index_modules = True
|
||||
api_doc_dir = reference/api
|
||||
autodoc_exclude_modules =
|
||||
oslo_db.tests.*
|
||||
|
|
|
|||
54
tox.ini
54
tox.ini
|
|
@ -1,34 +1,29 @@
|
|||
[tox]
|
||||
minversion = 2.0
|
||||
envlist = py35,py27,pep8
|
||||
envlist = py27,py35,pep8
|
||||
|
||||
[testenv]
|
||||
install_command = pip install {opts} {packages}
|
||||
whitelist_externals = bash
|
||||
env
|
||||
whitelist_externals =
|
||||
env
|
||||
passenv =
|
||||
OS_TEST_DBAPI_ADMIN_CONNECTION
|
||||
setenv =
|
||||
VIRTUAL_ENV={envdir}
|
||||
BASECOMMAND=stestr run
|
||||
BRANCH_NAME=master
|
||||
CLIENT_NAME=oslo.db
|
||||
|
||||
{postgresql,all}: PIFPAF_POSTGRESQL=pifpaf -g OS_TEST_DBAPI_ADMIN_CONNECTION run postgresql --
|
||||
{mysql,all}: PIFPAF_MYSQL=pifpaf -g OS_TEST_DBAPI_ADMIN_CONNECTION run mysql --
|
||||
{mysql,postgresql,all}: BASECOMMAND={toxinidir}/tools/run-pifpaf-tests.sh
|
||||
BASECOMMAND=stestr run
|
||||
{postgresql,all}: PIFPAF_POSTGRESQL=pifpaf -g OS_TEST_DBAPI_ADMIN_CONNECTION run postgresql --
|
||||
{mysql,all}: PIFPAF_MYSQL=pifpaf -g OS_TEST_DBAPI_ADMIN_CONNECTION run mysql --
|
||||
{mysql,postgresql,all}: BASECOMMAND={toxinidir}/tools/run-pifpaf-tests.sh
|
||||
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
|
||||
-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
|
||||
commands =
|
||||
{env:PIFPAF_MYSQL:} {env:PIFPAF_POSTGRESQL:} {env:BASECOMMAND:} {posargs}
|
||||
|
||||
passenv = OS_TEST_DBAPI_ADMIN_CONNECTION
|
||||
|
||||
[testenv:py27]
|
||||
basepython = python2.7
|
||||
commands =
|
||||
env TEST_EVENTLET=0 stestr run {posargs}
|
||||
env TEST_EVENTLET=1 stestr run {posargs}
|
||||
env TEST_EVENTLET=0 stestr run {posargs}
|
||||
env TEST_EVENTLET=1 stestr run {posargs}
|
||||
|
||||
[testenv:pep8]
|
||||
basepython = python3
|
||||
|
|
@ -44,19 +39,24 @@ commands = {posargs}
|
|||
[testenv:cover]
|
||||
basepython = python3
|
||||
setenv =
|
||||
PYTHON=coverage run --source oslo_db --parallel-mode
|
||||
PYTHON=coverage run --source oslo_db --parallel-mode
|
||||
commands =
|
||||
stestr run {posargs}
|
||||
coverage combine
|
||||
coverage html -d cover
|
||||
coverage xml -o cover/coverage.xml
|
||||
stestr run {posargs}
|
||||
coverage combine
|
||||
coverage html -d cover
|
||||
coverage xml -o cover/coverage.xml
|
||||
|
||||
[testenv:docs]
|
||||
basepython = python3
|
||||
deps = -r{toxinidir}/doc/requirements.txt
|
||||
whitelist_externals =
|
||||
rm
|
||||
deps =
|
||||
{[testenv]deps}
|
||||
-r{toxinidir}/doc/requirements.txt
|
||||
commands =
|
||||
doc8 -e .rst CONTRIBUTING.rst HACKING.rst README.rst doc/source
|
||||
sphinx-build -b html doc/source doc/build/html
|
||||
rm -rf doc/build doc/source/reference/api
|
||||
doc8 -e .rst CONTRIBUTING.rst HACKING.rst README.rst doc/source
|
||||
sphinx-build -W -b html doc/source doc/build/html
|
||||
|
||||
[testenv:releasenotes]
|
||||
basepython = python3
|
||||
|
|
|
|||
Loading…
Reference in New Issue