diff --git a/conda/meta.yaml b/conda/meta.yaml
index 1467f96cf8b1bca8cedf6c3f05725bb840c74f4c..c6fcbf51ca9c50f54833122b0408681ba5ed16da 100644
--- a/conda/meta.yaml
+++ b/conda/meta.yaml
@@ -129,6 +129,9 @@ test:
- coverage
- sphinx
- sphinx_rtd_theme
+ - sphinxcontrib-programoutput
+ - graphviz
+ - font-ttf-dejavu-sans-mono
about:
home: https://www.idiap.ch/software/bob/
diff --git a/doc/_static/copybutton.js b/doc/_static/copybutton.js
new file mode 100644
index 0000000000000000000000000000000000000000..16dee0057947859dc5a4e8dc6ea1983f682238f3
--- /dev/null
+++ b/doc/_static/copybutton.js
@@ -0,0 +1,64 @@
+$(document).ready(function() {
+ /* Add a [>>>] button on the top-right corner of code samples to hide
+ * the >>> and ... prompts and the output and thus make the code
+ * copyable. */
+ var div = $('.highlight-python .highlight,' +
+ '.highlight-python3 .highlight,' +
+ '.highlight-pycon .highlight,' +
+ '.highlight-pycon3 .highlight,' +
+ '.highlight-default .highlight');
+ var pre = div.find('pre');
+
+ // get the styles from the current theme
+ pre.parent().parent().css('position', 'relative');
+ var hide_text = 'Hide the prompts and output';
+ var show_text = 'Show the prompts and output';
+ var border_width = pre.css('border-top-width');
+ var border_style = pre.css('border-top-style');
+ var border_color = pre.css('border-top-color');
+ var button_styles = {
+ 'cursor':'pointer', 'position': 'absolute', 'top': '0', 'right': '0',
+ 'border-color': border_color, 'border-style': border_style,
+ 'border-width': border_width, 'color': border_color, 'text-size': '75%',
+ 'font-family': 'monospace', 'padding-left': '0.2em', 'padding-right': '0.2em',
+ 'border-radius': '0 3px 0 0'
+ }
+
+ // create and add the button to all the code blocks that contain >>>
+ div.each(function(index) {
+ var jthis = $(this);
+ if (jthis.find('.gp').length > 0) {
+ var button = $('<span class="copybutton">>>></span>');
+ button.css(button_styles)
+ button.attr('title', hide_text);
+ button.data('hidden', 'false');
+ jthis.prepend(button);
+ }
+ // tracebacks (.gt) contain bare text elements that need to be
+ // wrapped in a span to work with .nextUntil() (see later)
+ jthis.find('pre:has(.gt)').contents().filter(function() {
+ return ((this.nodeType == 3) && (this.data.trim().length > 0));
+ }).wrap('<span>');
+ });
+
+ // define the behavior of the button when it's clicked
+ $('.copybutton').click(function(e){
+ e.preventDefault();
+ var button = $(this);
+ if (button.data('hidden') === 'false') {
+ // hide the code output
+ button.parent().find('.go, .gp, .gt').hide();
+ button.next('pre').find('.gt').nextUntil('.gp, .go').css('visibility', 'hidden');
+ button.css('text-decoration', 'line-through');
+ button.attr('title', show_text);
+ button.data('hidden', 'true');
+ } else {
+ // show the code output
+ button.parent().find('.go, .gp, .gt').show();
+ button.next('pre').find('.gt').nextUntil('.gp, .go').css('visibility', 'visible');
+ button.css('text-decoration', 'none');
+ button.attr('title', hide_text);
+ button.data('hidden', 'false');
+ }
+ });
+});
diff --git a/doc/_templates/config.rst b/doc/_templates/config.rst
new file mode 100644
index 0000000000000000000000000000000000000000..a287392f705f1c10adec86c2e2e5a1b0b1c9cb24
--- /dev/null
+++ b/doc/_templates/config.rst
@@ -0,0 +1,2 @@
+{% include "autosummary/module.rst" %}
+.. literalinclude:: ../../../../{{ fullname.replace(".", "/") }}.py
diff --git a/doc/conf.py b/doc/conf.py
index 59c22fdb480c78565953cd73eb793eecf39bff3a..0b6f474ca5c827ec0a193eaeba5eb1e1e6867016 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -2,32 +2,30 @@
# vim: set fileencoding=utf-8 :
import os
-import sys
-import glob
import pkg_resources
# -- General configuration -----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
-needs_sphinx = '1.3'
+needs_sphinx = "1.3"
# 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.todo',
- 'sphinx.ext.coverage',
- 'sphinx.ext.ifconfig',
- 'sphinx.ext.autodoc',
- 'sphinx.ext.autosummary',
- 'sphinx.ext.doctest',
- 'sphinx.ext.graphviz',
- 'sphinx.ext.intersphinx',
- 'sphinx.ext.napoleon',
- 'sphinx.ext.viewcode',
- 'sphinx.ext.mathjax',
- 'matplotlib.sphinxext.plot_directive'
- ]
+ "sphinx.ext.todo",
+ "sphinx.ext.coverage",
+ "sphinx.ext.ifconfig",
+ "sphinx.ext.autodoc",
+ "sphinx.ext.autosummary",
+ "sphinx.ext.doctest",
+ "sphinx.ext.graphviz",
+ "sphinx.ext.intersphinx",
+ "sphinx.ext.napoleon",
+ "sphinx.ext.viewcode",
+ "sphinx.ext.mathjax",
+ "matplotlib.sphinxext.plot_directive",
+]
# matplotlib.sphinxext.plot_directive
plot_basedir = None
@@ -39,13 +37,13 @@ nitpicky = False
nitpick_ignore = []
# Allows the user to override warnings from a separate file
-if os.path.exists('nitpick-exceptions.txt'):
- for line in open('nitpick-exceptions.txt'):
+if os.path.exists("nitpick-exceptions.txt"):
+ for line in open("nitpick-exceptions.txt"):
if line.strip() == "" or line.startswith("#"):
continue
dtype, target = line.split(None, 1)
target = target.strip()
- try: # python 2.x
+ try: # python 2.x
target = unicode(target)
except NameError:
pass
@@ -61,25 +59,27 @@ autosummary_generate = True
numfig = True
# If we are on OSX, the 'dvipng' path maybe different
-dvipng_osx = '/opt/local/libexec/texlive/binaries/dvipng'
-if os.path.exists(dvipng_osx): pngmath_dvipng = dvipng_osx
+dvipng_osx = "/opt/local/libexec/texlive/binaries/dvipng"
+if os.path.exists(dvipng_osx):
+ pngmath_dvipng = dvipng_osx
# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
# The suffix of source filenames.
-source_suffix = '.rst'
+source_suffix = ".rst"
# The encoding of source files.
-#source_encoding = 'utf-8-sig'
+# source_encoding = 'utf-8-sig'
# The master toctree document.
-master_doc = 'index'
+master_doc = "index"
# General information about the project.
-project = u'bob'
+project = u"bob"
import time
-copyright = u'%s, Idiap Research Institute' % time.strftime('%Y')
+
+copyright = u"%s, Idiap Research Institute" % time.strftime("%Y")
# Grab the setup entry
distribution = pkg_resources.require(project)[0]
@@ -95,42 +95,42 @@ release = distribution.version
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
-#language = None
+# language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
-#today = ''
+# today = ''
# Else, today_fmt is used as the format for a strftime call.
-#today_fmt = '%B %d, %Y'
+# today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
-exclude_patterns = ['links.rst']
+exclude_patterns = ["links.rst"]
# The reST default role (used for this markup: `text`) to use for all documents.
-#default_role = None
+# default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
+# 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
+# add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
-#show_authors = False
+# show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = "sphinx"
# A list of ignored prefixes for module index sorting.
-#modindex_common_prefix = []
+# modindex_common_prefix = []
# Some variables which are useful for generated material
-project_variable = project.replace('.', '_')
-short_description = u'Bob (All Packages)'
-owner = [u'Idiap Research Institute']
+project_variable = project.replace(".", "_")
+short_description = u"Bob (All Packages)"
+owner = [u"Idiap Research Institute"]
# -- Options for HTML output ---------------------------------------------------
@@ -138,80 +138,81 @@ owner = [u'Idiap Research Institute']
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
import sphinx_rtd_theme
-html_theme = 'sphinx_rtd_theme'
+
+html_theme = "sphinx_rtd_theme"
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
-#html_theme_options = {}
+# html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
-#html_title = None
+# html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
-#html_short_title = project_variable
+# html_short_title = project_variable
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
-html_logo = 'img/logo.png'
+html_logo = "img/logo.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 = 'img/favicon.ico'
+html_favicon = "img/favicon.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']
+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'
+# 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
+# html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
+# html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
-#html_additional_pages = {}
+# html_additional_pages = {}
# If false, no module index is generated.
-#html_domain_indices = True
+# html_domain_indices = True
# If false, no index is generated.
-#html_use_index = True
+# html_use_index = True
# If true, the index is split into individual pages for each letter.
-#html_split_index = False
+# html_split_index = False
# If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
+# html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-#html_show_sphinx = True
+# html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#html_show_copyright = True
+# html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
-#html_use_opensearch = ''
+# html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
-#html_file_suffix = None
+# html_file_suffix = None
# Output file base name for HTML help builder.
-htmlhelp_basename = project_variable + u'_doc'
+htmlhelp_basename = project_variable + u"_doc"
# -- Post configuration --------------------------------------------------------
@@ -221,19 +222,22 @@ rst_epilog = """
.. |project| replace:: Bob
.. |version| replace:: %s
.. |current-year| date:: %%Y
-""" % (version,)
+""" % (
+ version,
+)
# Default processing flags for sphinx
-autoclass_content = 'class'
-autodoc_member_order = 'bysource'
+autoclass_content = "class"
+autodoc_member_order = "bysource"
autodoc_default_options = {
- 'members': True,
- 'undoc-members': True,
- 'show-inheritance': True,
+ "members": True,
+ "undoc-members": True,
+ "show-inheritance": True,
}
# For inter-documentation mapping:
-from bob.extension.utils import link_documentation, load_requirements
+from bob.extension.utils import link_documentation
+
sphinx_requirements = "extra-intersphinx.txt"
if os.path.exists(sphinx_requirements):
intersphinx_mapping = link_documentation(requirements_file=sphinx_requirements)
@@ -243,20 +247,26 @@ else:
# We want to remove all private (i.e. _. or __.__) members
# that are not in the list of accepted functions
-accepted_private_functions = ['__array__']
+accepted_private_functions = ["__array__"]
+
def member_function_test(app, what, name, obj, skip, options):
- # test if we have a private function
- if len(name) > 1 and name[0] == '_':
- # test if this private function should be allowed
- if name not in accepted_private_functions:
- # omit privat functions that are not in the list of accepted private functions
- return skip
- else:
- # test if the method is documented
- if not hasattr(obj, '__doc__') or not obj.__doc__:
- return skip
- return False
+ # test if we have a private function
+ if len(name) > 1 and name[0] == "_":
+ # test if this private function should be allowed
+ if name not in accepted_private_functions:
+ # omit privat functions that are not in the list of accepted private functions
+ return skip
+ else:
+ # test if the method is documented
+ if not hasattr(obj, "__doc__") or not obj.__doc__:
+ return skip
+ return False
+
def setup(app):
- app.connect('autodoc-skip-member', member_function_test)
+ app.connect("autodoc-skip-member", member_function_test)
+ # Add `>>>` button to toggle visibility of prompts in code blocks.
+ # see https://github.com/readthedocs/sphinx_rtd_theme/issues/167 and
+ # https://raw.githubusercontent.com/python/python-docs-theme/master/python_docs_theme/static/copybutton.js
+ app.add_javascript("copybutton.js")