diff options
author | Nguyen Hai <nguyentrihai93@gmail.com> | 2018-03-16 01:35:19 +0900 |
---|---|---|
committer | Nguyen Hai <nguyentrihai93@gmail.com> | 2018-04-06 14:33:47 +0000 |
commit | 7ba42e091dad82b134f3acf73c72edccaca84830 (patch) | |
tree | 0cda91605e5bc22a46b343e69d32603af14445c6 | |
parent | f5605d13e67c71c46538bafa5f7ddc18fb7427a6 (diff) | |
download | ironic-7ba42e091dad82b134f3acf73c72edccaca84830.tar.gz |
Follow the new PTI for document build
For compliance with the Project Testing Interface as described in:
[1] https://governance.openstack.org/tc/reference/project-testing-interface.html
[2] http://lists.openstack.org/pipermail/openstack-dev/2017-December/125710.html
[doc/requirements.txt] & [test-requirements.txt]
To support documentation generation in new PTI, project should have
list python dependencies needed for documentation in
doc/requirements.txt which are move from test-requirements.txt
[doc/source/contributor/index.rst] & [setup.cfg]
- Remove [pbr] section in setup.cfg [3], and unrelated lines in
contributor/index.rst
[3] http://lists.openstack.org/pipermail/openstack-dev/2018-March/128594.html
- Add sphinxcontrib.apidoc to replace pbr autodoc
[tox.ini]
--ignore D000: pep8 require sphinx (which move to doc/requirements.txt)
to test doc/source files, however, docs already test the doc/source.
Therefore we can ignore the D000 error code.
Depends-On: https://review.openstack.org/#/c/559327/
Change-Id: Iee90f19a5e46978a97035eab7e4b1e0ec68b8684
-rw-r--r-- | doc/requirements.txt | 7 | ||||
-rw-r--r-- | doc/source/conf.py | 13 | ||||
-rw-r--r-- | doc/source/contributor/index.rst | 7 | ||||
-rw-r--r-- | setup.cfg | 14 | ||||
-rw-r--r-- | test-requirements.txt | 8 | ||||
-rw-r--r-- | tox.ini | 24 |
6 files changed, 34 insertions, 39 deletions
diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 000000000..77d1fe88b --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,7 @@ +openstackdocstheme>=1.18.1 # Apache-2.0 +os-api-ref>=1.4.0 # Apache-2.0 +reno>=2.5.0 # Apache-2.0 +sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD +sphinxcontrib-apidoc>=0.2.0 # BSD +sphinxcontrib-pecanwsme>=0.8.0 # Apache-2.0 +sphinxcontrib-seqdiag>=0.8.4 # BSD diff --git a/doc/source/conf.py b/doc/source/conf.py index 9c1ffe278..313bb4ae9 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -24,12 +24,12 @@ except TypeError: # 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.viewcode', +extensions = ['sphinx.ext.viewcode', 'sphinx.ext.graphviz', 'sphinxcontrib.httpdomain', 'sphinxcontrib.pecanwsme.rest', 'sphinxcontrib.seqdiag', + 'sphinxcontrib.apidoc', 'wsmeext.sphinxext', 'oslo_config.sphinxext', 'oslo_config.sphinxconfiggen', @@ -43,6 +43,15 @@ try: except ImportError: openstackdocstheme = None +# sphinxcontrib.apidoc options +apidoc_module_dir = '../../ironic' +apidoc_output_dir = 'contributor/api' +apidoc_excluded_paths = [ + 'db/sqlalchemy/alembic/env' + 'db/sqlalchemy/alembic/versions/*', + 'drivers/modules/ansible/playbooks*'] +apidoc_separate_modules = True + repository_name = 'openstack/ironic' bug_project = 'ironic' bug_tag = '' diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 94a347be3..73b33d9b8 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -91,10 +91,7 @@ booting from Cinder volumes with VMs. Full Ironic Server Python API Reference --------------------------------------- -* :ref:`modindex` - -.. # api/autoindex is hidden since it's in the modindex link above. .. toctree:: - :hidden: + :maxdepth: 1 - api/autoindex + api/modules @@ -189,20 +189,6 @@ ironic.hardware.types = ironic.database.migration_backend = sqlalchemy = ironic.db.sqlalchemy.migration -[pbr] -autodoc_index_modules = True -autodoc_exclude_modules = - ironic.db.sqlalchemy.alembic.env - ironic.db.sqlalchemy.alembic.versions.* - ironic.drivers.modules.ansible.playbooks* -api_doc_dir = contributor/api - -[build_sphinx] -all_files = 1 -build-dir = doc/build -source-dir = doc/source -warning-is-error = 1 - [egg_info] tag_build = tag_date = 0 diff --git a/test-requirements.txt b/test-requirements.txt index 558dddd2a..eeea491e0 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -18,11 +18,3 @@ testscenarios>=0.4 # Apache-2.0/BSD WebTest>=2.0.27 # MIT bashate>=0.5.1 # Apache-2.0 flake8-import-order>=0.13 # LGPLv3 - -# Doc requirements -sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD -sphinxcontrib-pecanwsme>=0.8.0 # Apache-2.0 -sphinxcontrib-seqdiag>=0.8.4 # BSD -openstackdocstheme>=1.18.1 # Apache-2.0 -reno>=2.5.0 # Apache-2.0 -os-api-ref>=1.4.0 # Apache-2.0 @@ -35,7 +35,7 @@ commands = # the check and gate queues. {toxinidir}/tools/run_bashate.sh {toxinidir} # Check the *.rst files - doc8 README.rst CONTRIBUTING.rst doc/source --ignore D001 + doc8 README.rst CONTRIBUTING.rst doc/source --ignore D001 --ignore D000 # Check to make sure reno releasenotes created with 'reno new' {toxinidir}/tools/check-releasenotes.py @@ -72,23 +72,27 @@ commands = commands = oslo_debug_helper -t ironic/tests/unit {posargs} [testenv:docs] -# FIXME(dtantsur): workaround for bug #1714025 -basepython = python2 -setenv = PYTHONHASHSEED=0 -sitepackages = False -envdir = {toxworkdir}/venv -commands = - python setup.py build_sphinx +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 = sphinx-build -W -b html doc/source doc/build/html [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}/requirements.txt + -r{toxinidir}/doc/requirements.txt whitelist_externals = bash commands = bash -c 'rm -rf api-ref/build' sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html [testenv:releasenotes] +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 = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html |