Updating for new sphinx docs jobs

There have been recent changes to how docs jobs are run under zuul [1].
This patch updates neutron-lbaas-dashboard to be able to run under the
new zuul docs jobs.

[1] https://review.openstack.org/#/c/508694/

Change-Id: I482b4904838f39e7e32eb499ef9a29a4ec349522
This commit is contained in:
Jacky Hu 2018-01-19 12:12:46 +08:00
parent c6fdca4847
commit 92584d239b
9 changed files with 97 additions and 15 deletions

3
.gitignore vendored
View File

@ -24,8 +24,10 @@ pip-log.txt
# Unit test / coverage reports
.coverage
*.lock
.tox
nosetests.xml
.secret_key_store
.testrepository
node_modules
coverage*
@ -46,6 +48,7 @@ output/*/index.html
# Sphinx
doc/build
doc/source/contributor/modules
# pbr generates these
AUTHORS

2
doc/requirements.txt Normal file
View File

@ -0,0 +1,2 @@
openstackdocstheme>=1.17.0 # Apache-2.0
sphinx!=1.6.6,>=1.6.2 # BSD

View File

@ -12,18 +12,33 @@
# See the License for the specific language governing permissions and
# limitations under the License.
import logging
import os
import sys
from sphinx import apidoc
import django
sys.path.insert(0, os.path.abspath('../..'))
sys.path.insert(0, os.path.abspath('.'))
logging.getLogger('openstack_dashboard.settings').setLevel(logging.ERROR)
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'openstack_dashboard.settings')
django.setup()
# -- 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 = [
'openstackdocstheme',
'sphinx.ext.autodoc',
#'sphinx.ext.intersphinx',
'oslosphinx'
'sphinx.ext.coverage',
# 'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.viewcode',
]
# autodoc generation is a bit aggressive and a nuisance when doing heavy
@ -57,6 +72,13 @@ pygments_style = 'sphinx'
# html_theme_path = ["."]
# html_theme = '_theme'
# html_static_path = ['static']
html_theme = 'openstackdocs'
html_theme_options = {
'display_toc': False
}
html_static_path = []
# Output file base name for HTML help builder.
htmlhelp_basename = '%sdoc' % project
@ -72,7 +94,34 @@ latex_documents = [
]
# Example configuration for intersphinx: refer to the Python standard library.
#intersphinx_mapping = {'http://docs.python.org/': None}
# intersphinx_mapping = {'http://docs.python.org/': None}
# A list of ignored prefixes for module index sorting.
modindex_common_prefix = ['neutron-lbaas-dashboard.']
# TODO(mordred) We should extract this into a sphinx plugin
def run_apidoc(_):
cur_dir = os.path.abspath(os.path.dirname(__file__))
out_dir = os.path.join(cur_dir, 'contributor', 'modules')
module = os.path.join(cur_dir, '..', '..', 'neutron_lbaas_dashboard')
# Keep the order of arguments same as the sphinx-apidoc help, otherwise it
# would cause unexpected errors:
# sphinx-apidoc [options] -o <output_path> <module_path>
# [exclude_pattern, ...]
apidoc.main([
'--force',
'-o',
out_dir,
module,
'neutron_lbaas_dashboard/tests',
'neutron_lbaas_dashboard/enabled',
'neutron_lbaas_dashboard/locale',
'neutron_lbaas_dashboard/static',
'neutron_lbaas_dashboard/post_install.sh',
'neutron_lbaas_dashboard/karma.conf.js'
])
def setup(app):
app.connect('builder-inited', run_apidoc)

View File

@ -15,11 +15,4 @@ Contents:
installation
usage
contributing
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
reference

16
doc/source/reference.rst Normal file
View File

@ -0,0 +1,16 @@
=========
Reference
=========
Indices and search
------------------
.. toctree::
:hidden:
contributor/modules/modules
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

View File

@ -2,6 +2,7 @@
# of appearance. Changing the order has an impact on the overall integration
# process, which may cause wedges in the gate later.
oslo.log>=3.36.0 # Apache-2.0
pbr!=2.1.0,>=2.0.0 # Apache-2.0
Babel!=2.4.0,>=2.3.4 # BSD
python-barbicanclient!=4.5.0,!=4.5.1,>=4.0.0 # Apache-2.0

View File

@ -29,5 +29,18 @@ all_files = 1
upload-dir = doc/build/html
[pbr]
autodoc_index_modules = True
autodoc_tree_index_modules = False
autodoc_tree_excludes =
setup.py
neutron_lbaas_dashboard/tests
neutron_lbaas_dashboard/enabled
neutron_lbaas_dashboard/locale
neutron_lbaas_dashboard/static
neutron_lbaas_dashboard/post_install.sh
neutron_lbaas_dashboard/karma.conf.js
autodoc_index_modules = False
warnerrors = True
autodoc_exclude_modules =
neutron_lbaas_dashboard.tests.*
neutron_lbaas_dashboard.enabled.*
api_doc_dir = contributor/modules

View File

@ -9,8 +9,6 @@ django-nose>=1.4.4 # BSD
python-subunit>=1.0.0 # Apache-2.0/BSD
nose-exclude>=0.3.0 # LGPL
selenium>=2.50.1 # Apache-2.0
sphinx!=1.6.6,>=1.6.2 # BSD
oslosphinx>=4.7.0 # Apache-2.0
oslotest>=3.2.0 # Apache-2.0
testrepository>=0.0.18 # Apache-2.0/BSD
testscenarios>=0.4 # Apache-2.0/BSD

View File

@ -40,7 +40,14 @@ commands = nosetests neutron_lbaas_dashboard/tests/integration_tests/tests {posa
commands = python setup.py test --coverage --testr-args='{posargs}'
[testenv:docs]
commands = python setup.py build_sphinx
whitelist_externals = rm
deps =
-c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt}
-r{toxinidir}/requirements.txt
-r{toxinidir}/doc/requirements.txt
commands =
rm -rf doc/build
sphinx-build -W -b html doc/source doc/build/html
[testenv:debug]
commands = oslo_debug_helper {posargs}