diff --git a/.gitignore b/.gitignore index 4001f8a..e2a1e88 100644 --- a/.gitignore +++ b/.gitignore @@ -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 diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 0000000..11de1b0 --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,2 @@ +openstackdocstheme>=1.17.0 # Apache-2.0 +sphinx!=1.6.6,>=1.6.2 # BSD diff --git a/doc/source/conf.py b/doc/source/conf.py index 2eda35b..a2b48bf 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -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 + # [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) diff --git a/doc/source/index.rst b/doc/source/index.rst index 881551f..658eeec 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -15,11 +15,4 @@ Contents: installation usage contributing - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - + reference diff --git a/doc/source/reference.rst b/doc/source/reference.rst new file mode 100644 index 0000000..28e9fb4 --- /dev/null +++ b/doc/source/reference.rst @@ -0,0 +1,16 @@ +========= +Reference +========= + +Indices and search +------------------ + +.. toctree:: + :hidden: + + contributor/modules/modules + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/requirements.txt b/requirements.txt index 735b56f..30bd101 100644 --- a/requirements.txt +++ b/requirements.txt @@ -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 diff --git a/setup.cfg b/setup.cfg index b8c3c17..c89723f 100644 --- a/setup.cfg +++ b/setup.cfg @@ -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 diff --git a/test-requirements.txt b/test-requirements.txt index 0c57868..8e391d4 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -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 diff --git a/tox.ini b/tox.ini index 9dc2f26..36f6b76 100644 --- a/tox.ini +++ b/tox.ini @@ -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}