Updating for new sphinx docs jobs

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

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

Change-Id: I44f7ce2538de0ce76860a3a2b477751de322ab02
This commit is contained in:
Jacky Hu 2018-01-11 09:45:43 +08:00
parent 941c6ddcb1
commit f6a5e91cb1
8 changed files with 99 additions and 17 deletions

3
.gitignore vendored
View File

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

3
doc/requirements.txt Normal file
View File

@ -0,0 +1,3 @@
openstackdocstheme>=1.17.0 # Apache-2.0
oslosphinx>=4.7.0 # Apache-2.0
sphinx>=1.6.2 # BSD

View File

@ -12,18 +12,34 @@
# See the License for the specific language governing permissions and # See the License for the specific language governing permissions and
# limitations under the License. # limitations under the License.
import logging
import os import os
import sys import sys
from sphinx import apidoc
import django
sys.path.insert(0, os.path.abspath('../..')) 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 ---------------------------------------------------- # -- General configuration ----------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be # Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [ extensions = [
'openstackdocstheme',
'oslosphinx',
'sphinx.ext.autodoc', 'sphinx.ext.autodoc',
#'sphinx.ext.intersphinx', 'sphinx.ext.coverage',
'oslosphinx' # 'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.viewcode',
] ]
# autodoc generation is a bit aggressive and a nuisance when doing heavy # autodoc generation is a bit aggressive and a nuisance when doing heavy
@ -57,6 +73,13 @@ pygments_style = 'sphinx'
# html_theme_path = ["."] # html_theme_path = ["."]
# html_theme = '_theme' # html_theme = '_theme'
# html_static_path = ['static'] # html_static_path = ['static']
html_theme = 'openstackdocs'
html_theme_options = {
'display_toc': False
}
html_static_path = []
# Output file base name for HTML help builder. # Output file base name for HTML help builder.
htmlhelp_basename = '%sdoc' % project htmlhelp_basename = '%sdoc' % project
@ -72,7 +95,34 @@ latex_documents = [
] ]
# Example configuration for intersphinx: refer to the Python standard library. # 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. # A list of ignored prefixes for module index sorting.
modindex_common_prefix = ['octavia-dashboard.'] modindex_common_prefix = ['octavia-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, '..', '..', 'octavia_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,
'octavia_dashboard/tests',
'octavia_dashboard/enabled',
'octavia_dashboard/locale',
'octavia_dashboard/static',
'octavia_dashboard/post_install.sh',
'octavia_dashboard/karma.conf.js'
])
def setup(app):
app.connect('builder-inited', run_apidoc)

View File

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

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

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

View File

@ -8,13 +8,10 @@ django-nose>=1.4.4 # BSD
python-subunit>=1.0.0 # Apache-2.0/BSD python-subunit>=1.0.0 # Apache-2.0/BSD
nose-exclude>=0.3.0 # LGPL nose-exclude>=0.3.0 # LGPL
selenium>=2.50.1 # Apache-2.0 selenium>=2.50.1 # Apache-2.0
sphinx>=1.6.2 # BSD
oslosphinx>=4.7.0 # Apache-2.0
oslotest>=1.10.0 # Apache-2.0 oslotest>=1.10.0 # Apache-2.0
testrepository>=0.0.18 # Apache-2.0/BSD testrepository>=0.0.18 # Apache-2.0/BSD
testscenarios>=0.4 # Apache-2.0/BSD testscenarios>=0.4 # Apache-2.0/BSD
testtools>=2.2.0 # MIT testtools>=2.2.0 # MIT
reno>=2.5.0 # Apache-2.0 reno>=2.5.0 # Apache-2.0
openstackdocstheme>=1.17.0 # Apache-2.0
# This also needs xvfb library installed on your OS # This also needs xvfb library installed on your OS
xvfbwrapper>=0.1.3 #license: MIT xvfbwrapper>=0.1.3 #license: MIT

10
tox.ini
View File

@ -40,7 +40,15 @@ commands = nosetests octavia_dashboard/tests/integration_tests/tests {posargs}
commands = python setup.py test --coverage --testr-args='{posargs}' commands = python setup.py test --coverage --testr-args='{posargs}'
[testenv:docs] [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:releasenotes] [testenv:releasenotes]
commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html