From 4fd0ac7bda5f0550edc2a699ef27fdd8290b8137 Mon Sep 17 00:00:00 2001 From: John Tyree Date: Tue, 6 May 2014 23:03:47 -0500 Subject: [PATCH 1/7] Add make target for docset to be used with Dash/Zeal --- docs/Makefile | 4 + docs/source/docset_resources/conf.py | 189 +++++++++++++++++++++++++++ 2 files changed, 193 insertions(+) create mode 100644 docs/source/docset_resources/conf.py diff --git a/docs/Makefile b/docs/Makefile index f333c63993..4e8ff645db 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -87,3 +87,7 @@ 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: + $(SPHINXBUILD) -b html -c source/docset_resources $(ALLSPHINXOPTS) $(BUILDDIR)/docset_html + doc2dash -f -d $(BUILDDIR) -i $(BUILDDIR)/docset_html/_static/e-logo-rev.png -n Traits $(BUILDDIR)/docset_html diff --git a/docs/source/docset_resources/conf.py b/docs/source/docset_resources/conf.py new file mode 100644 index 0000000000..b4cd70153f --- /dev/null +++ b/docs/source/docset_resources/conf.py @@ -0,0 +1,189 @@ +# -*- coding: utf-8 -*- +# +# Traits documentation build configuration file, created by +# sphinx-quickstart on Tue Jul 22 10:52:03 2008. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# The contents of this file are pickled, so don't put values in the namespace +# that aren't pickleable (module imports are okay, they're removed automatically). +# +# All configuration values have a default value; values that are commented out +# serve to show the default value. + +import sys +import os + +# If your extensions are in another directory, add it here. If the directory +# is relative to the documentation root, use os.path.abspath to make it +# absolute, like shown here. +sys.path.append(os.path.abspath('../_extensions')) +sys.path.append(os.path.abspath('../../../')) + +# 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 = ['refactordoc', + 'sphinx.ext.viewcode', + 'sphinx.ext.autosummary', + 'traits.util.trait_documenter'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['../_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General substitutions. +project = 'traits' +copyright = '2008-2014, Enthought' + +# The default replacements for |version| and |release|, also used in various +# other places throughout the built documents. +d = {} +execfile(os.path.join('..', '..', '..', 'traits', '__init__.py'), d) +version = release = d['__version__'] + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +today_fmt = '%B %d, %Y' + +# List of documents that shouldn't be included in the build. +#unused_docs = [] + +# List of directories, relative to source directories, that shouldn't be searched +# for source files. +#exclude_dirs = [] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +autodoc_default_flags =['members'] + +# Options for HTML output +# ----------------------- + +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. +html_style = 'default.css' + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +html_title = "Traits 4 User Manual" + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (within the static path) to place at the top of +# the sidebar. +html_logo = "e-logo-rev.png" + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +html_favicon = "et.ico" + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['../_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +# html_use_modindex = False + +# If false, no index is generated. +html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, the reST sources are included in the HTML build as _sources/. +#html_copy_source = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = '' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Traitsdoc' + + +# Options for LaTeX output +# ------------------------ + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, document class [howto/manual]). +latex_documents = [ + ('index', 'Traits.tex', 'Traits 4 User Manual', 'Enthought, Inc.', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +# latex_logo = "enthought_logo.jpg" +latex_logo = "e-logo-rev.png" + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_use_modindex = True + +autodoc_member_order = 'bysource' From 81c48070c58db66f8ae838ad9422dce92cb4f34d Mon Sep 17 00:00:00 2001 From: John Tyree Date: Tue, 6 May 2014 23:43:18 -0500 Subject: [PATCH 2/7] Improve make target status output during build --- docs/Makefile | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/Makefile b/docs/Makefile index 2e7d4b3f14..53e75fe7d4 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -106,4 +106,6 @@ info: docset: $(SPHINXBUILD) -b html -c source/docset_resources $(ALLSPHINXOPTS) $(BUILDDIR)/docset_html + @echo "Creating docset with doc2dash" doc2dash -f -d $(BUILDDIR) -i $(BUILDDIR)/docset_html/_static/e-logo-rev.png -n Traits $(BUILDDIR)/docset_html + @echo "Traits docset is available in $(BUILDDIR)/Traits.docset" From 43a15f3231eabb73a91eef90ec2a65361c4c0be6 Mon Sep 17 00:00:00 2001 From: John Tyree Date: Thu, 29 May 2014 18:41:28 -0500 Subject: [PATCH 3/7] STY: some pep8 fixes --- docs/source/conf.py | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 89447ac90c..41b3776676 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -3,10 +3,12 @@ # Traits documentation build configuration file, created by # sphinx-quickstart on Tue Jul 22 10:52:03 2008. # -# This file is execfile()d with the current directory set to its containing dir. +# This file is execfile()d with the current directory set to its containing +# dir. # # The contents of this file are pickled, so don't put values in the namespace -# that aren't pickleable (module imports are okay, they're removed automatically). +# that aren't pickleable (module imports are okay, they're removed +# automatically). # # All configuration values have a default value; values that are commented out # serve to show the default value. @@ -22,12 +24,12 @@ # 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 = [ 'refactordoc', - 'sphinx.ext.viewcode', - 'sphinx.ext.autosummary', - 'traits.util.trait_documenter'] +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['refactordoc', + 'sphinx.ext.viewcode', + 'sphinx.ext.autosummary', + 'traits.util.trait_documenter'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -57,11 +59,12 @@ # List of documents that shouldn't be included in the build. #unused_docs = [] -# List of directories, relative to source directories, that shouldn't be searched -# for source files. +# List of directories, relative to source directories, that shouldn't be +# searched for source files. #exclude_dirs = [] -# The reST default role (used for this markup: `text`) to use for all documents. +# The reST default role (used for this markup: `text`) to use for all +# documents. #default_role = None # If true, '()' will be appended to :func: etc. cross-reference text. @@ -79,7 +82,7 @@ pygments_style = 'sphinx' # Options for the autodoc extension. -autodoc_default_flags =['members'] +autodoc_default_flags = ['members'] autodoc_member_order = 'bysource' @@ -162,7 +165,8 @@ #latex_font_size = '10pt' # Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, document class [howto/manual]). +# (source start file, target name, title, author, +# document class [howto/manual]). latex_documents = [ ('index', 'Traits.tex', 'Traits 4 User Manual', 'Enthought, Inc.', 'manual'), ] From b46cf5481deb386982e0a37ee12cb7c9a621d85c Mon Sep 17 00:00:00 2001 From: John Tyree Date: Thu, 29 May 2014 18:42:20 -0500 Subject: [PATCH 4/7] ENH: use ENV var to config for docset building --- docs/Makefile | 2 +- docs/source/conf.py | 16 +++++++++++++--- 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 53e75fe7d4..11526f3a37 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -105,7 +105,7 @@ info: @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." docset: - $(SPHINXBUILD) -b html -c source/docset_resources $(ALLSPHINXOPTS) $(BUILDDIR)/docset_html + BUILD_DOCSET=1 $(SPHINXBUILD) -b html -c source/docset_resources $(ALLSPHINXOPTS) $(BUILDDIR)/docset_html @echo "Creating docset with doc2dash" doc2dash -f -d $(BUILDDIR) -i $(BUILDDIR)/docset_html/_static/e-logo-rev.png -n Traits $(BUILDDIR)/docset_html @echo "Traits docset is available in $(BUILDDIR)/Traits.docset" diff --git a/docs/source/conf.py b/docs/source/conf.py index 41b3776676..3ccf2c7382 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -13,7 +13,11 @@ # All configuration values have a default value; values that are commented out # serve to show the default value. -import sys, os +import sys +import os + +# The docset version will use slightly different formatting rules +BUILD_DOCSET = bool(os.environ.get('BUILD_DOCSET')) # If your extensions are in another directory, add it here. If the directory # is relative to the documentation root, use os.path.abspath to make it @@ -90,6 +94,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. @@ -132,10 +142,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 From 43f32005ceccaec1cb885c3d93fb600bdf59d1b9 Mon Sep 17 00:00:00 2001 From: John Tyree Date: Thu, 29 May 2014 18:42:36 -0500 Subject: [PATCH 5/7] MNT: bump copyright --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 3ccf2c7382..f445ebcbbe 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -46,7 +46,7 @@ # General substitutions. project = 'traits' -copyright = '2008-2011, Enthought' +copyright = '2008-2014, Enthought' # The default replacements for |version| and |release|, also used in various # other places throughout the built documents. From dc3f3b1b87ac9405909016469c95a2e7564e92bd Mon Sep 17 00:00:00 2001 From: John Tyree Date: Thu, 29 May 2014 18:58:09 -0500 Subject: [PATCH 6/7] DOC: fix outdated directory in makefile for docset --- docs/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Makefile b/docs/Makefile index 11526f3a37..c3cd9c2d9c 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -105,7 +105,7 @@ info: @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." docset: - BUILD_DOCSET=1 $(SPHINXBUILD) -b html -c source/docset_resources $(ALLSPHINXOPTS) $(BUILDDIR)/docset_html + BUILD_DOCSET=1 $(SPHINXBUILD) -b html -c source/ $(ALLSPHINXOPTS) $(BUILDDIR)/docset_html @echo "Creating docset with doc2dash" doc2dash -f -d $(BUILDDIR) -i $(BUILDDIR)/docset_html/_static/e-logo-rev.png -n Traits $(BUILDDIR)/docset_html @echo "Traits docset is available in $(BUILDDIR)/Traits.docset" From 7b345aad0064815ec8a352966c7d5e04f98124ea Mon Sep 17 00:00:00 2001 From: John Tyree Date: Thu, 29 May 2014 18:58:43 -0500 Subject: [PATCH 7/7] STY: disambiguate comment in sphinx conf --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index f445ebcbbe..99daf1153b 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -16,7 +16,7 @@ import sys import os -# The docset version will use slightly different formatting rules +# The docset build will use slightly different formatting rules BUILD_DOCSET = bool(os.environ.get('BUILD_DOCSET')) # If your extensions are in another directory, add it here. If the directory