1# -*- coding: utf-8 -*- 2# 3# skimage documentation build configuration file, created by 4# sphinx-quickstart on Sat Aug 22 13:00:30 2009. 5# 6# This file is execfile()d with the current directory set to its containing dir. 7# 8# Note that not all possible configuration values are present in this 9# autogenerated file. 10# 11# All configuration values have a default; values that are commented out 12# serve to show the default. 13 14import sys 15import os 16import skimage 17from sphinx_gallery.sorting import ExplicitOrder 18from warnings import filterwarnings 19filterwarnings('ignore', message="Matplotlib is currently using agg", 20 category=UserWarning) 21 22# If extensions (or modules to document with autodoc) are in another directory, 23# add these directories to sys.path here. If the directory is relative to the 24# documentation root, use os.path.abspath to make it absolute, like shown here. 25#sys.path.append(os.path.abspath('.')) 26 27curpath = os.path.dirname(__file__) 28sys.path.append(os.path.join(curpath, '..', 'ext')) 29 30# -- General configuration ----------------------------------------------------- 31 32# Add any Sphinx extension module names here, as strings. They can be extensions 33# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. 34extensions = ['sphinx_copybutton', 35 'sphinx.ext.autodoc', 36 'sphinx.ext.mathjax', 37 'numpydoc', 38 'doi_role', 39 'sphinx.ext.autosummary', 40 'sphinx.ext.intersphinx', 41 'sphinx.ext.linkcode', 42 'sphinx_gallery.gen_gallery', 43 'myst_parser', 44 ] 45 46autosummary_generate = True 47 48# Determine if the matplotlib has a recent enough version of the 49# plot_directive, otherwise use the local fork. 50try: 51 from matplotlib.sphinxext import plot_directive 52except ImportError: 53 use_matplotlib_plot_directive = False 54else: 55 try: 56 use_matplotlib_plot_directive = (plot_directive.__version__ >= 2) 57 except AttributeError: 58 use_matplotlib_plot_directive = False 59 60if use_matplotlib_plot_directive: 61 extensions.append('matplotlib.sphinxext.plot_directive') 62else: 63 extensions.append('plot_directive') 64 65# Add any paths that contain templates here, relative to this directory. 66templates_path = ['_templates'] 67 68# The suffix of source filenames. 69source_suffix = '.rst' 70 71# The encoding of source files. 72#source_encoding = 'utf-8-sig' 73 74# The master toctree document. 75# Changes to `root_doc` in newest versions of Sphinx (we're still on v2) 76master_doc = 'index' 77 78# General information about the project. 79project = 'skimage' 80copyright = '2013, the scikit-image team' 81 82# The version info for the project you're documenting, acts as replacement for 83# |version| and |release|, also used in various other places throughout the 84# built documents. 85# 86# The short X.Y version. 87 88with open('../../skimage/__init__.py') as f: 89 setup_lines = f.readlines() 90version = 'vUndefined' 91for l in setup_lines: 92 if l.startswith('__version__'): 93 version = l.split("'")[1] 94 break 95 96# The full version, including alpha/beta/rc tags. 97release = version 98 99# The language for content autogenerated by Sphinx. Refer to documentation 100# for a list of supported languages. 101#language = None 102 103# There are two options for replacing |today|: either, you set today to some 104# non-false value, then it is used: 105#today = '' 106# Else, today_fmt is used as the format for a strftime call. 107#today_fmt = '%B %d, %Y' 108 109# List of documents that shouldn't be included in the build. 110#unused_docs = [] 111 112# List of directories, relative to source directory, that shouldn't be searched 113# for source files. 114exclude_trees = [] 115 116# The reST default role (used for this markup: `text`) to use for all documents. 117default_role = "autolink" 118 119# If true, '()' will be appended to :func: etc. cross-reference text. 120#add_function_parentheses = True 121 122# If true, the current module name will be prepended to all description 123# unit titles (such as .. function::). 124#add_module_names = True 125 126# If true, sectionauthor and moduleauthor directives will be shown in the 127# output. They are ignored by default. 128#show_authors = False 129 130# The name of the Pygments (syntax highlighting) style to use. 131pygments_style = 'sphinx' 132 133# A list of ignored prefixes for module index sorting. 134#modindex_common_prefix = [] 135 136#------------------------------------------------------------------------ 137# Sphinx-gallery configuration 138#------------------------------------------------------------------------ 139 140from packaging.version import parse 141v = parse(release) 142if v.release is None: 143 raise ValueError( 144 f'Ill-formed version: {version!r}. Version should follow ' 145 f'PEP440') 146 147if v.is_devrelease: 148 binder_branch = 'main' 149else: 150 major, minor = v.release[:2] 151 binder_branch = f'v{major}.{minor}.x' 152 153# set plotly renderer to capture _repr_html_ for sphinx-gallery 154import plotly.io as pio 155pio.renderers.default = 'sphinx_gallery_png' 156from plotly.io._sg_scraper import plotly_sg_scraper 157image_scrapers = ('matplotlib', plotly_sg_scraper,) 158 159sphinx_gallery_conf = { 160 'doc_module': ('skimage',), 161 # path to your examples scripts 162 'examples_dirs': '../examples', 163 # path where to save gallery generated examples 164 'gallery_dirs': 'auto_examples', 165 'backreferences_dir': 'api', 166 'reference_url': {'skimage': None}, 167 'image_scrapers': image_scrapers, 168 # Default thumbnail size (400, 280) 169 # Default CSS rescales (160, 112) 170 # Size is decreased to reduce webpage loading time 171 'thumbnail_size': (280, 196), 172 'subsection_order': ExplicitOrder([ 173 '../examples/data', 174 '../examples/numpy_operations', 175 '../examples/color_exposure', 176 '../examples/edges', 177 '../examples/transform', 178 '../examples/registration', 179 '../examples/filters', 180 '../examples/features_detection', 181 '../examples/segmentation', 182 '../examples/applications', 183 '../examples/developers', 184 ]), 185 'binder': { 186 # Required keys 187 'org': 'scikit-image', 188 'repo': 'scikit-image', 189 'branch': binder_branch, # Can be any branch, tag, or commit hash 190 'binderhub_url': 'https://mybinder.org', # Any URL of a binderhub. 191 'dependencies': '../../.binder/requirements.txt', 192 # Optional keys 193 'use_jupyter_lab': False 194 }, 195 # Remove sphinx_gallery_thumbnail_number from generated files 196 'remove_config_comments':True, 197} 198 199from sphinx_gallery.utils import _has_optipng 200if _has_optipng(): 201 # This option requires optipng to compress images 202 # Optimization level between 0-7 203 # sphinx-gallery default: -o7 204 # optipng default: -o2 205 # We choose -o1 as it produces a sufficient optimization 206 # See #4800 207 sphinx_gallery_conf['compress_images'] = ('images', 'thumbnails', '-o1') 208 209 210# -- Options for HTML output --------------------------------------------------- 211 212# The theme to use for HTML and HTML Help pages. Major themes that come with 213# Sphinx are currently 'default' and 'sphinxdoc'. 214html_theme = 'scikit-image' 215 216# Theme options are theme-specific and customize the look and feel of a theme 217# further. For a list of options available for each theme, see the 218# documentation. 219#html_theme_options = {} 220 221# Add any paths that contain custom themes here, relative to this directory. 222html_theme_path = ['themes'] 223 224# The name for this set of Sphinx documents. If None, it defaults to 225# "<project> v<release> documentation". 226html_title = 'skimage v%s docs' % version 227 228# A shorter title for the navigation bar. Default is the same as html_title. 229#html_short_title = None 230 231# The name of an image file (within the static path) to use as favicon of the 232# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 233# pixels large. 234html_favicon = '_static/favicon.ico' 235 236# Add any paths that contain custom static files (such as style sheets) here, 237# relative to this directory. They are copied after the builtin static files, 238# so a file named "default.css" will overwrite the builtin "default.css". 239html_static_path = ['_static'] 240 241# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, 242# using the given strftime format. 243#html_last_updated_fmt = '%b %d, %Y' 244 245# If true, SmartyPants will be used to convert quotes and dashes to 246# typographically correct entities. 247#html_use_smartypants = True 248 249# Custom sidebar templates, maps document names to template names. 250html_sidebars = { 251 '**': ['searchbox.html', 252 'navigation.html', 253 'localtoc.html', 254 'versions.html'], 255} 256 257# Additional templates that should be rendered to pages, maps page names to 258# template names. 259# html_additional_pages = {} 260 261# If false, no module index is generated. 262#html_use_modindex = True 263 264# If false, no index is generated. 265#html_use_index = True 266 267# If true, the index is split into individual pages for each letter. 268#html_split_index = False 269 270# If true, links to the reST sources are added to the pages. 271#html_show_sourcelink = True 272 273# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. 274#html_show_sphinx = True 275 276# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. 277#html_show_copyright = True 278 279# If true, an OpenSearch description file will be output, and all pages will 280# contain a <link> tag referring to it. The value of this option must be the 281# base URL from which the finished HTML is served. 282#html_use_opensearch = '' 283 284# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). 285#html_file_suffix = '' 286 287# Output file base name for HTML help builder. 288htmlhelp_basename = 'scikitimagedoc' 289 290 291# -- Options for LaTeX output -------------------------------------------------- 292 293# The paper size ('letter' or 'a4'). 294#latex_paper_size = 'letter' 295 296# The font size ('10pt', '11pt' or '12pt'). 297latex_font_size = '10pt' 298 299# Grouping the document tree into LaTeX files. List of tuples 300# (source start file, target name, title, author, documentclass [howto/manual]). 301latex_documents = [ 302 ('index', 'scikit-image.tex', u'The scikit-image Documentation', 303 u'scikit-image development team', 'manual'), 304] 305 306# The name of an image file (relative to this directory) to place at the top of 307# the title page. 308#latex_logo = None 309 310# For "manual" documents, if this is true, then toplevel headings are parts, 311# not chapters. 312#latex_use_parts = False 313 314# Additional stuff for the LaTeX preamble. 315latex_elements = {} 316latex_elements['preamble'] = r''' 317\usepackage{enumitem} 318\setlistdepth{100} 319 320\usepackage{amsmath} 321\DeclareUnicodeCharacter{00A0}{\nobreakspace} 322 323% In the parameters section, place a newline after the Parameters header 324\usepackage{expdlist} 325\let\latexdescription=\description 326\def\description{\latexdescription{}{} \breaklabel} 327 328% Make Examples/etc section headers smaller and more compact 329\makeatletter 330\titleformat{\paragraph}{\normalsize\py@HeaderFamily}% 331 {\py@TitleColor}{0em}{\py@TitleColor}{\py@NormalColor} 332\titlespacing*{\paragraph}{0pt}{1ex}{0pt} 333\makeatother 334 335''' 336 337# Documents to append as an appendix to all manuals. 338#latex_appendices = [] 339 340# If false, no module index is generated. 341latex_domain_indices = False 342 343# ----------------------------------------------------------------------------- 344# Numpy extensions 345# ----------------------------------------------------------------------------- 346numpydoc_show_class_members = False 347numpydoc_class_members_toctree = False 348 349# ----------------------------------------------------------------------------- 350# Plots 351# ----------------------------------------------------------------------------- 352plot_basedir = os.path.join(curpath, "plots") 353plot_pre_code = """ 354import numpy as np 355import matplotlib.pyplot as plt 356 357import matplotlib 358matplotlib.rcParams.update({ 359 'font.size': 14, 360 'axes.titlesize': 12, 361 'axes.labelsize': 10, 362 'xtick.labelsize': 8, 363 'ytick.labelsize': 8, 364 'legend.fontsize': 10, 365 'figure.subplot.bottom': 0.2, 366 'figure.subplot.left': 0.2, 367 'figure.subplot.right': 0.9, 368 'figure.subplot.top': 0.85, 369 'figure.subplot.wspace': 0.4, 370 'text.usetex': False, 371}) 372 373""" 374plot_include_source = True 375plot_formats = [('png', 100), ('pdf', 100)] 376 377plot2rst_index_name = 'README' 378plot2rst_rcparams = {'image.cmap' : 'gray', 379 'image.interpolation' : 'none'} 380 381# ----------------------------------------------------------------------------- 382# intersphinx 383# ----------------------------------------------------------------------------- 384_python_version_str = f'{sys.version_info.major}.{sys.version_info.minor}' 385_python_doc_base = 'https://docs.python.org/' + _python_version_str 386intersphinx_mapping = { 387 'python': (_python_doc_base, None), 388 'numpy': ('https://numpy.org/doc/stable', 389 (None, './_intersphinx/numpy-objects.inv')), 390 'scipy': ('https://docs.scipy.org/doc/scipy/reference', 391 (None, './_intersphinx/scipy-objects.inv')), 392 'sklearn': ('https://scikit-learn.org/stable', 393 (None, './_intersphinx/sklearn-objects.inv')), 394 'matplotlib': ('https://matplotlib.org/', 395 (None, './_intersphinx/matplotlib-objects.inv')) 396} 397 398# ---------------------------------------------------------------------------- 399# Source code links 400# ---------------------------------------------------------------------------- 401 402import inspect 403from os.path import relpath, dirname 404 405 406# Function courtesy of NumPy to return URLs containing line numbers 407def linkcode_resolve(domain, info): 408 """ 409 Determine the URL corresponding to Python object 410 """ 411 if domain != 'py': 412 return None 413 414 modname = info['module'] 415 fullname = info['fullname'] 416 417 submod = sys.modules.get(modname) 418 if submod is None: 419 return None 420 421 obj = submod 422 for part in fullname.split('.'): 423 try: 424 obj = getattr(obj, part) 425 except: 426 return None 427 428 # Strip decorators which would resolve to the source of the decorator 429 obj = inspect.unwrap(obj) 430 431 try: 432 fn = inspect.getsourcefile(obj) 433 except: 434 fn = None 435 if not fn: 436 return None 437 438 try: 439 source, start_line = inspect.getsourcelines(obj) 440 except: 441 linespec = "" 442 else: 443 stop_line = start_line + len(source) - 1 444 linespec = f'#L{start_line}-L{stop_line}' 445 446 fn = relpath(fn, start=dirname(skimage.__file__)) 447 448 if 'dev' in skimage.__version__: 449 return ("https://github.com/scikit-image/scikit-image/blob/" 450 "main/skimage/%s%s" % (fn, linespec)) 451 else: 452 return ("https://github.com/scikit-image/scikit-image/blob/" 453 "v%s/skimage/%s%s" % (skimage.__version__, fn, linespec)) 454