conf.py 11.5 KB
Newer Older
1 2
#!/usr/bin/env python
# vim: set fileencoding=utf-8 :
André Anjos's avatar
André Anjos committed
3

4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35
###################################################################################
#                                                                                 #
# Copyright (c) 2019 Idiap Research Institute, http://www.idiap.ch/               #
# Contact: beat.support@idiap.ch                                                  #
#                                                                                 #
# Redistribution and use in source and binary forms, with or without              #
# modification, are permitted provided that the following conditions are met:     #
#                                                                                 #
# 1. Redistributions of source code must retain the above copyright notice, this  #
# list of conditions and the following disclaimer.                                #
#                                                                                 #
# 2. Redistributions in binary form must reproduce the above copyright notice,    #
# this list of conditions and the following disclaimer in the documentation       #
# and/or other materials provided with the distribution.                          #
#                                                                                 #
# 3. Neither the name of the copyright holder nor the names of its contributors   #
# may be used to endorse or promote products derived from this software without   #
# specific prior written permission.                                              #
#                                                                                 #
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND #
# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED   #
# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE          #
# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE    #
# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL      #
# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR      #
# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER      #
# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,   #
# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE   #
# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.            #
#                                                                                 #
###################################################################################

André Anjos's avatar
André Anjos committed
36

André Anjos's avatar
André Anjos committed
37
import os
Samuel GAIST's avatar
Samuel GAIST committed
38 39
import time

André Anjos's avatar
André Anjos committed
40 41
import pkg_resources

Samuel GAIST's avatar
Samuel GAIST committed
42 43 44 45 46 47 48
# For inter-documentation mapping:
from bob.extension.utils import link_documentation
from bob.extension.utils import load_requirements

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
import sphinx_rtd_theme
André Anjos's avatar
André Anjos committed
49 50 51 52

# -- General configuration -----------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.
Samuel GAIST's avatar
Samuel GAIST committed
53
needs_sphinx = "1.3"
André Anjos's avatar
André Anjos committed
54 55 56 57

# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [
Samuel GAIST's avatar
Samuel GAIST committed
58 59 60 61 62 63 64 65 66 67 68 69 70
    "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",
    "sphinxcontrib.programoutput",
]
André Anjos's avatar
André Anjos committed
71

André Anjos's avatar
André Anjos committed
72
# Use buildout-installed version of beat cmdline if available
Samuel GAIST's avatar
Samuel GAIST committed
73
bindir = os.path.join(os.path.dirname(os.path.dirname(__file__)), "bin")
André Anjos's avatar
André Anjos committed
74
if os.path.exists(bindir):
Samuel GAIST's avatar
Samuel GAIST committed
75
    os.environ["PATH"] = bindir + os.pathsep + os.environ["PATH"]
André Anjos's avatar
André Anjos committed
76

André Anjos's avatar
André Anjos committed
77 78 79 80 81 82 83
# Be picky about warnings
nitpicky = True

# Ignores stuff we can't easily resolve on other project's sphinx manuals
nitpick_ignore = []

# Allows the user to override warnings from a separate file
Samuel GAIST's avatar
Samuel GAIST committed
84 85
if os.path.exists("nitpick-exceptions.txt"):
    for line in open("nitpick-exceptions.txt"):
André Anjos's avatar
André Anjos committed
86 87 88 89
        if line.strip() == "" or line.startswith("#"):
            continue
        dtype, target = line.split(None, 1)
        target = target.strip()
Samuel GAIST's avatar
Samuel GAIST committed
90
        try:  # python 2.x
André Anjos's avatar
André Anjos committed
91 92 93 94
            target = unicode(target)
        except NameError:
            pass
        nitpick_ignore.append((dtype, target))
André Anjos's avatar
André Anjos committed
95 96 97 98 99 100 101

# Always includes todos
todo_include_todos = True

# Generates auto-summary automatically
autosummary_generate = True

André Anjos's avatar
André Anjos committed
102 103 104
# Create numbers on figures with captions
numfig = True

André Anjos's avatar
André Anjos committed
105
# If we are on OSX, the 'dvipng' path maybe different
Samuel GAIST's avatar
Samuel GAIST committed
106 107 108
dvipng_osx = "/Library/TeX/texbin/dvipng"
if os.path.exists(dvipng_osx):
    pngmath_dvipng = dvipng_osx
André Anjos's avatar
André Anjos committed
109 110

# Add any paths that contain templates here, relative to this directory.
Samuel GAIST's avatar
Samuel GAIST committed
111
templates_path = ["_templates"]
André Anjos's avatar
André Anjos committed
112 113

# The suffix of source filenames.
Samuel GAIST's avatar
Samuel GAIST committed
114
source_suffix = ".rst"
André Anjos's avatar
André Anjos committed
115 116

# The encoding of source files.
Samuel GAIST's avatar
Samuel GAIST committed
117
# source_encoding = 'utf-8-sig'
André Anjos's avatar
André Anjos committed
118 119

# The master toctree document.
Samuel GAIST's avatar
Samuel GAIST committed
120
master_doc = "index"
André Anjos's avatar
André Anjos committed
121 122

# General information about the project.
Samuel GAIST's avatar
Samuel GAIST committed
123 124
project = u"beat.cmdline"
copyright = u"%s, Idiap Research Institute" % time.strftime("%Y")
André Anjos's avatar
André Anjos committed
125 126 127 128 129 130 131 132 133 134 135 136 137 138 139

# Grab the setup entry
distribution = pkg_resources.require(project)[0]

# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = distribution.version
# The full version, including alpha/beta/rc tags.
release = distribution.version

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
Samuel GAIST's avatar
Samuel GAIST committed
140
# language = None
André Anjos's avatar
André Anjos committed
141 142 143

# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
Samuel GAIST's avatar
Samuel GAIST committed
144
# today = ''
André Anjos's avatar
André Anjos committed
145
# Else, today_fmt is used as the format for a strftime call.
Samuel GAIST's avatar
Samuel GAIST committed
146
# today_fmt = '%B %d, %Y'
André Anjos's avatar
André Anjos committed
147 148 149

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
Samuel GAIST's avatar
Samuel GAIST committed
150
exclude_patterns = ["links.rst"]
André Anjos's avatar
André Anjos committed
151 152

# The reST default role (used for this markup: `text`) to use for all documents.
Samuel GAIST's avatar
Samuel GAIST committed
153
# default_role = None
André Anjos's avatar
André Anjos committed
154 155

# If true, '()' will be appended to :func: etc. cross-reference text.
Samuel GAIST's avatar
Samuel GAIST committed
156
# add_function_parentheses = True
André Anjos's avatar
André Anjos committed
157 158 159

# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
Samuel GAIST's avatar
Samuel GAIST committed
160
# add_module_names = True
André Anjos's avatar
André Anjos committed
161 162 163

# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
Samuel GAIST's avatar
Samuel GAIST committed
164
# show_authors = False
André Anjos's avatar
André Anjos committed
165 166

# The name of the Pygments (syntax highlighting) style to use.
Samuel GAIST's avatar
Samuel GAIST committed
167
pygments_style = "sphinx"
André Anjos's avatar
André Anjos committed
168 169

# A list of ignored prefixes for module index sorting.
Samuel GAIST's avatar
Samuel GAIST committed
170
# modindex_common_prefix = []
André Anjos's avatar
André Anjos committed
171 172

# Some variables which are useful for generated material
Samuel GAIST's avatar
Samuel GAIST committed
173 174 175
project_variable = project.replace(".", "_")
short_description = u"Command-line client for the BEAT platform"
owner = [u"Idiap Research Institute"]
André Anjos's avatar
André Anjos committed
176 177 178 179


# -- Options for HTML output ---------------------------------------------------

Samuel GAIST's avatar
Samuel GAIST committed
180
html_theme = "sphinx_rtd_theme"
André Anjos's avatar
André Anjos committed
181 182 183 184

# 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.
Samuel GAIST's avatar
Samuel GAIST committed
185
# html_theme_options = {}
André Anjos's avatar
André Anjos committed
186 187

# Add any paths that contain custom themes here, relative to this directory.
188
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
André Anjos's avatar
André Anjos committed
189 190 191

# The name for this set of Sphinx documents.  If None, it defaults to
# "<project> v<release> documentation".
Samuel GAIST's avatar
Samuel GAIST committed
192
# html_title = None
André Anjos's avatar
André Anjos committed
193 194

# A shorter title for the navigation bar.  Default is the same as html_title.
Samuel GAIST's avatar
Samuel GAIST committed
195
# html_short_title = project_variable
André Anjos's avatar
André Anjos committed
196 197 198

# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
Samuel GAIST's avatar
Samuel GAIST committed
199
html_logo = "img/logo.png"
André Anjos's avatar
André Anjos committed
200 201 202 203

# 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.
Samuel GAIST's avatar
Samuel GAIST committed
204
html_favicon = "img/favicon.ico"
André Anjos's avatar
André Anjos committed
205 206 207 208

# 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".
Samuel GAIST's avatar
Samuel GAIST committed
209
# html_static_path = ['_static']
André Anjos's avatar
André Anjos committed
210 211 212

# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
Samuel GAIST's avatar
Samuel GAIST committed
213
# html_last_updated_fmt = '%b %d, %Y'
André Anjos's avatar
André Anjos committed
214 215 216

# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
Samuel GAIST's avatar
Samuel GAIST committed
217
# html_use_smartypants = True
André Anjos's avatar
André Anjos committed
218 219

# Custom sidebar templates, maps document names to template names.
Samuel GAIST's avatar
Samuel GAIST committed
220
# html_sidebars = {}
André Anjos's avatar
André Anjos committed
221 222 223

# Additional templates that should be rendered to pages, maps page names to
# template names.
Samuel GAIST's avatar
Samuel GAIST committed
224
# html_additional_pages = {}
André Anjos's avatar
André Anjos committed
225 226

# If false, no module index is generated.
Samuel GAIST's avatar
Samuel GAIST committed
227
# html_domain_indices = True
André Anjos's avatar
André Anjos committed
228 229

# If false, no index is generated.
Samuel GAIST's avatar
Samuel GAIST committed
230
# html_use_index = True
André Anjos's avatar
André Anjos committed
231 232

# If true, the index is split into individual pages for each letter.
Samuel GAIST's avatar
Samuel GAIST committed
233
# html_split_index = False
André Anjos's avatar
André Anjos committed
234 235

# If true, links to the reST sources are added to the pages.
Samuel GAIST's avatar
Samuel GAIST committed
236
# html_show_sourcelink = True
André Anjos's avatar
André Anjos committed
237 238

# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
Samuel GAIST's avatar
Samuel GAIST committed
239
# html_show_sphinx = True
André Anjos's avatar
André Anjos committed
240 241

# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
Samuel GAIST's avatar
Samuel GAIST committed
242
# html_show_copyright = True
André Anjos's avatar
André Anjos committed
243 244 245 246

# 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.
Samuel GAIST's avatar
Samuel GAIST committed
247
# html_use_opensearch = ''
André Anjos's avatar
André Anjos committed
248 249

# This is the file name suffix for HTML files (e.g. ".xhtml").
Samuel GAIST's avatar
Samuel GAIST committed
250
# html_file_suffix = None
André Anjos's avatar
André Anjos committed
251 252

# Output file base name for HTML help builder.
Samuel GAIST's avatar
Samuel GAIST committed
253
htmlhelp_basename = project_variable + u"_doc"
André Anjos's avatar
André Anjos committed
254 255


André Anjos's avatar
André Anjos committed
256
# -- Post configuration --------------------------------------------------------
André Anjos's avatar
André Anjos committed
257 258 259 260 261 262

# Included after all input documents
rst_epilog = """
.. |project| replace:: BEAT
.. |version| replace:: %s
.. |current-year| date:: %%Y
Samuel GAIST's avatar
Samuel GAIST committed
263 264 265
""" % (
    version,
)
André Anjos's avatar
André Anjos committed
266 267

# Default processing flags for sphinx
Samuel GAIST's avatar
Samuel GAIST committed
268 269
autoclass_content = "class"
autodoc_member_order = "bysource"
270 271 272 273 274
autodoc_default_options = {
  "members": True,
  "undoc-members": True,
  "show-inheritance": True,
}
Samuel GAIST's avatar
Samuel GAIST committed
275 276 277 278 279 280 281

if "BOB_DOCUMENTATION_SERVER" not in os.environ:
    # notice we need to overwrite this for BEAT projects - defaults from Bob are
    # not OK
    os.environ[
        "BOB_DOCUMENTATION_SERVER"
    ] = "https://www.idiap.ch/software/beat/docs/beat/%(name)s/%(version)s/|https://www.idiap.ch/software/beat/docs/beat/%(name)s/master/"
André Anjos's avatar
André Anjos committed
282 283 284

sphinx_requirements = "extra-intersphinx.txt"
if os.path.exists(sphinx_requirements):
Samuel GAIST's avatar
Samuel GAIST committed
285 286 287
    intersphinx_mapping = link_documentation(
        additional_packages=["python", "numpy"] + load_requirements(sphinx_requirements)
    )
André Anjos's avatar
André Anjos committed
288
else:
Samuel GAIST's avatar
Samuel GAIST committed
289
    intersphinx_mapping = link_documentation()
André Anjos's avatar
André Anjos committed
290

André Anjos's avatar
André Anjos committed
291 292 293
# Excludes the "Usage" docstrings from these modules to appear in the API
# documentation
exclude_docstrings = {
Samuel GAIST's avatar
Samuel GAIST committed
294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309
    "beat.cmdline.databases": "module",
    "beat.cmdline.databases.process": "function",
    "beat.cmdline.algorithms": "module",
    "beat.cmdline.algorithms.process": "function",
    "beat.cmdline.libraries": "module",
    "beat.cmdline.libraries.process": "function",
    "beat.cmdline.toolchains": "module",
    "beat.cmdline.toolchains.process": "function",
    "beat.cmdline.experiments": "module",
    "beat.cmdline.experiments.process": "function",
    "beat.cmdline.plotters": "module",
    "beat.cmdline.plotters.process": "function",
    "beat.cmdline.config": "module",
    "beat.cmdline.config.process": "function",
}

André Anjos's avatar
André Anjos committed
310 311

def remove_module_docstring(app, what, name, obj, options, lines):
Samuel GAIST's avatar
Samuel GAIST committed
312 313 314
    if name in exclude_docstrings and what == exclude_docstrings[name]:
        del lines[:]

André Anjos's avatar
André Anjos committed
315

André Anjos's avatar
André Anjos committed
316
def setup(app):
Samuel GAIST's avatar
Samuel GAIST committed
317
    app.connect("autodoc-process-docstring", remove_module_docstring)