From 8bdee46fa4d5466582ffcfda2cf9c3b4e8ad95d7 Mon Sep 17 00:00:00 2001 From: Shu Muto Date: Fri, 20 Apr 2018 15:51:57 +0900 Subject: [PATCH] Follow the new PTI for document build For compliance with the Project Testing Interface as described in: https://governance.openstack.org/tc/reference/project-testing-interface.html For more details information, please refer to: http://lists.openstack.org/pipermail/openstack-dev/2017-December/125710.html Change-Id: I8f3f9f1ae087b0abd5db0b0f58e83870ca49a529 --- doc/Makefile | 152 ------------------------------------------ doc/requirements.txt | 16 +++++ doc/source/conf.py | 10 ++- lower-constraints.txt | 1 + setup.cfg | 10 --- test-requirements.txt | 5 -- tox.ini | 19 ++---- 7 files changed, 32 insertions(+), 181 deletions(-) delete mode 100644 doc/Makefile create mode 100644 doc/requirements.txt diff --git a/doc/Makefile b/doc/Makefile deleted file mode 100644 index 4006293..0000000 --- a/doc/Makefile +++ /dev/null @@ -1,152 +0,0 @@ -# Makefile for Sphinx documentation - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = build - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - -rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Zun-UI.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Zun-UI.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/Zun-UI" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Zun-UI" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 0000000..e5a64cd --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,16 @@ +# The order of packages is significant, because pip processes them in the order +# of appearance. Changing the order has an impact on the overall integration +# process, which may cause wedges in the gate later. +# Order matters to the pip dependency resolver, so sorting this file +# changes how packages are installed. New dependencies should be +# added in alphabetical order, however, some dependencies may need to +# be installed in a specific order. +# +# Requirements for docs +django-nose>=1.4.4 # BSD +mock>=2.0.0 # BSD +mox3>=0.20.0 # Apache-2.0 +openstackdocstheme>=1.18.1 # 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 diff --git a/doc/source/conf.py b/doc/source/conf.py index 4542619..1d54b22 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -59,10 +59,10 @@ from zun_ui import version as zunui_ver # 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.todo', +extensions = ['sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.viewcode', + 'sphinxcontrib.apidoc', 'openstackdocstheme', ] @@ -129,6 +129,12 @@ pygments_style = 'sphinx' primary_domain = 'py' nitpicky = False +# sphinxcontrib-apidoc +apidoc_module_dir = '../../zun_ui' +apidoc_output_dir = 'contributor/api' +apidoc_excluded_paths = [ + 'test', +] # -- Options for HTML output -------------------------------------------------- diff --git a/lower-constraints.txt b/lower-constraints.txt index e6e5d55..2046b34 100644 --- a/lower-constraints.txt +++ b/lower-constraints.txt @@ -98,6 +98,7 @@ simplejson==3.13.2 six==1.11.0 snowballstemmer==1.2.1 Sphinx==1.6.2 +sphinxcontrib-apidoc===0.2.0 sphinxcontrib-websupport==1.0.1 stevedore==1.28.0 testtools==2.3.0 diff --git a/setup.cfg b/setup.cfg index 72d3d92..329e09f 100644 --- a/setup.cfg +++ b/setup.cfg @@ -21,13 +21,3 @@ classifier = [files] packages = zun_ui - -[build_sphinx] -all_files = 1 -build-dir = doc/build -source-dir = doc/source -warning-is-error = 1 - -[pbr] -autodoc_index_modules = True -api_doc_dir = contributor/api diff --git a/test-requirements.txt b/test-requirements.txt index bbcbd8a..9305280 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -14,8 +14,3 @@ django-nose>=1.4.4 # BSD mock>=2.0.0 # BSD mox3>=0.20.0 # Apache-2.0 testtools>=2.3.0 # MIT - -# For docs -sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD -openstackdocstheme>=1.18.1 # Apache-2.0 -reno>=2.5.0 # Apache-2.0 diff --git a/tox.ini b/tox.ini index 9ba9815..ade2969 100644 --- a/tox.ini +++ b/tox.ini @@ -87,22 +87,17 @@ commands = {toxinidir}/tools/tox_helper.sh {envname} {basepython} post [testenv:docs] -commands = - # Clean-up env and install horizon from git - {toxinidir}/tools/tox_helper.sh {envname} {basepython} pre - # Run test - python setup.py build_sphinx - # Clean-up env except log - {toxinidir}/tools/tox_helper.sh {envname} {basepython} post +deps = + -c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt} + -r{toxinidir}/doc/requirements.txt +commands= + sphinx-build -W -b html doc/source doc/build/html [testenv:releasenotes] +deps = + {[testenv:docs]deps} commands = - # Clean-up env and install horizon from git - {toxinidir}/tools/tox_helper.sh {envname} {basepython} pre - # Run test sphinx-build -a -E -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html - # Clean-up env except log - {toxinidir}/tools/tox_helper.sh {envname} {basepython} post [testenv:lower-constraints] basepython = python3