diff --git a/docs/Makefile b/docs/Makefile index f4e9a6661..c5e8c76a5 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -128,3 +128,9 @@ doctest: $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest @echo "Testing of doctests in the sources finished, look at the " \ "results in $(BUILDDIR)/doctest/output.txt." + +docset: + BUILD_DOCSET=1 $(SPHINXBUILD) -b html -c source/ $(ALLSPHINXOPTS) $(BUILDDIR)/docset_html + @echo "Creating docset with doc2dash" + doc2dash --force --destination $(BUILDDIR) --icon $(BUILDDIR)/docset_html/_static/et.png --name TraitsUI --online-redirect-url http://docs.enthought.com/traitsui/ --index-page index.html $(BUILDDIR)/docset_html + @echo "TraitsUI docset is available in $(BUILDDIR)/TraitsUI.docset" diff --git a/docs/source/conf.py b/docs/source/conf.py index 19aa9ca32..626f5ee57 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -23,9 +23,13 @@ # absolute, like shown here. #sys.path.append(os.path.abspath('some/directory')) +# The docset build will use slightly different formatting rules +BUILD_DOCSET = bool(os.environ.get('BUILD_DOCSET')) + # 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 = [ @@ -33,6 +37,10 @@ 'sphinx.ext.intersphinx', 'traits.util.trait_documenter' ] +if BUILD_DOCSET: + extensions.extend([ + 'sphinx.ext.autosummary', + ]) # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -100,6 +108,12 @@ # Options for HTML output # ----------------------- +# When using docset browsers like Dash and Zeal the side bar is redundant. +if BUILD_DOCSET: + html_theme_options = { + 'nosidebar': 'true' + } + # The style sheet to use for HTML and HTML Help pages. A file of that name # must exist either in Sphinx' static/ path, or in one of the custom paths # given in html_static_path. @@ -143,10 +157,10 @@ #html_additional_pages = {} # If false, no module index is generated. -html_use_modindex = False +html_use_modindex = BUILD_DOCSET # If false, no index is generated. -#html_use_index = False +html_use_index = BUILD_DOCSET # If true, the index is split into individual pages for each letter. #html_split_index = False diff --git a/etstool.py b/etstool.py index 7c29600a1..49cc56eb5 100644 --- a/etstool.py +++ b/etstool.py @@ -126,6 +126,10 @@ "enthought_sphinx_theme", } +doc_pip_dependencies = { + "doc2dash", +} + environment_vars = { 'pyside': {'ETS_TOOLKIT': 'qt4', 'QT_API': 'pyside'}, 'pyside2': {'ETS_TOOLKIT': 'qt4', 'QT_API': 'pyside2'}, @@ -269,8 +273,10 @@ def docs(runtime, toolkit, environment): """ parameters = get_parameters(runtime, toolkit, environment) packages = ' '.join(doc_dependencies) + packages_pip = ' '.join(doc_pip_dependencies) commands = [ "edm install -y -e {environment} " + packages, + "edm run -e {environment} -- pip install " + packages_pip, ] click.echo("Installing documentation tools in '{environment}'".format( **parameters)) @@ -280,6 +286,7 @@ def docs(runtime, toolkit, environment): os.chdir('docs') commands = [ "edm run -e {environment} -- make html", + "edm run -e {environment} -- make docset", ] click.echo("Building documentation in '{environment}'".format(**parameters)) try: