# -*- coding: utf-8 -*-
#
# Configuration file for the Sphinx documentation builder.
#
# This file does only contain a selection of the most common options. For a
# full list see the documentation:
# http://www.sphinx-doc.org/en/master/config
from __future__ import absolute_import, division, print_function, unicode_literals
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
import datetime
import pkg_resources
import os
import re
import sys
[docs]__this_file = os.path.abspath(__file__)
[docs]__this_dir = os.path.dirname(__this_file)
[docs]__root = os.path.dirname(__this_dir) # tk-houdini repository root
sys.path.insert(0, __root)
# -- Project information -----------------------------------------------------
# For logos, images used
[docs]author = "Shotgunsoftware, Joseph Yu, Liam Hoflay"
[docs]copyright = "{0.year}, {1}".format(datetime.date.today(), author)
# The short X.Y version and the full version, including alpha/beta/rc tags
# Used by other confis in this file so overriding with -D args won't work
# e.g. sphinx-build -D version=v1.1.0 release=v1.1.0
version = release = "v1.7.2+wwfx.1.4.0"
# -- General configuration ---------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
[docs]extensions = [
"sphinx.ext.extlinks",
"sphinx.ext.githubpages",
"sphinx.ext.intersphinx",
"sphinx.ext.napoleon",
"sphinx.ext.todo",
"sphinx.ext.viewcode",
"autoapi.extension",
]
# Add any paths that contain templates here, relative to this directory.
[docs]templates_path = ["_templates"]
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
[docs]source_suffix = [".rst", ".md"]
# The master toctree document.
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
[docs]exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "_autoapi_templates"]
# The name of the Pygments (syntax highlighting) style to use.
# A boolean that decides whether module names are prepended to all object names
# (for object types where a “module” of some kind is defined),
# e.g. for py:function directives. Default is True.
[docs]add_module_names = False
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
[docs]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 = {}
# A dictionary of values to pass into the template engine’s context for
# all pages. Single values can also be put in this dictionary using the
# -A command-line option of sphinx-build.
[docs]html_context = {
# https://github.com/rtfd/sphinx_rtd_theme/blob/a3ab477aaa23f3b7ab7d62c7abc2cc74102ab2b8/sphinx_rtd_theme/breadcrumbs.html#L45
"display_github": True,
"github_user": "wwfxuk",
"github_repo": "tk-houdini",
"github_version": version,
"conf_py_path": "/docs/",
}
# The URL which points to the root of the HTML documentation.
# It is used to indicate the location of document like canonical_url.
[docs]html_baseurl = "https://{github_user}.github.io/{github_repo}".format(**html_context)
# If given, this must be the name of an image file
# (path relative to the configuration directory) that is the logo of the docs.
# It is placed at the top of the sidebar;
# its width should therefore not exceed 200 pixels. Default: None.
# html_logo = "_static/icon_64_bw.png"
# If given, this must be the name of an image file
# (path relative to the configuration directory) that is the
# favicon of the docs. Modern browsers use this as the icon for tabs,
# windows and bookmarks. It should be a Windows-style icon file (.ico),
# which is 16x16 or 32x32 pixels large. Default: None.
# html_favicon = html_logo
# 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".
[docs]html_static_path = ["_static"]
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# The default sidebars (for documents that don't match any pattern) are
# defined by theme itself. Builtin themes are using these templates by
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
# 'searchbox.html']``.
#
# html_sidebars = {}
# -- Extension configuration -------------------------------------------------
# This value contains a list of modules to be mocked up.
# This is useful when some external dependencies are
# not met at build time and break the building process.
# You may only specify the root package of the
# dependencies themselves and omit the sub-modules:
# autodoc_mock_imports = []
# -- Options for todo extension ----------------------------------------------
# If true, `todo` and `todoList` produce output, else they produce nothing.
[docs]todo_include_todos = True
# -- Options for extlinks extension -------------------------------------------
[docs]extlinks = {
__role: (__template.format(**html_context), __prefix)
for __role, __template, __prefix in [
(
"ghpath",
"https://github.com/{github_user}/{github_repo}/tree/{github_version}/%s",
"<repo>/",
),
("pr", "https://github.com/{github_user}/{github_repo}/pull/%s", "PR #"),
("pull", "https://github.com/{github_user}/{github_repo}/pull/%s", "PR #"),
("issue", "https://github.com/{github_user}/{github_repo}/issue/%s", "Issue #"),
]
}
# -- Options for intersphinx extension ----------------------------------------
[docs]intersphinx_mapping = {
"python": ("https://docs.python.org/2", None), # Houdini < 18.0
"tkcore": ("https://developer.shotgunsoftware.com/tk-core", None),
}
# -- Options for auto-api extension ------------------------------------------
[docs]autoapi_member_order = "groupwise"
[docs]autoapi_template_dir = "_autoapi_templates"
# autoapi_python_use_implicit_namespaces = True # Require __init__.py in all folders
# autoapi_keep_files = True # For debugging
[docs]autoapi_dirs = [
os.path.join(__root, "docs"),
os.path.join(__root, "hooks", "node_handlers"),
os.path.join(__root, "hooks", "tk-multi-publish2", "basic"),
os.path.join(__root, "houdini", "scripts"),
os.path.join(__root, "python", "tk_houdini"),
]
[docs]def autoapi_prepare_jinja_env(env):
"""Extend Jinja environment with some ``os.path`` filters and our TOC subpath logic.
See `official autoapi_prepare_jinja_env documentation
<https://sphinx-autoapi.readthedocs.io/en/latest/reference/config.html#confval-autoapi_prepare_jinja_env>`_
"""
def pprint_attrs(obj, **kwargs):
"""Print Python object attributes, useful for debugging.
Try creating the following for debugging in ``_autoapi_templates.index.rst``:
.. code-block:: rst
.. code-block:: text
{{ pages|first|pprint_attrs }}
Args:
obj (object): Any object to debug.
kwargs (dict): Flags for internal ``pprint.pformat``.
Returns:
str: Pretty formatted
"""
from pprint import pformat
return pformat({attr: getattr(obj, attr) for attr in dir(obj)}, **kwargs)
def by_subpath(pages, prefix):
"""Filter top level pages under a ``autoapi_dirs`` path.
We also perform our own internal calculation to get "top level" pages since
``/autoapi/python/tk_houdini/index`` isn't marked as ``page.top_level_object``.
Args:
pages (list): Pages to filter by.
prefix (str): Path from ``autoapi_dirs`` to filter pages for.
Returns:
list: Pages "to display" whose source was found under given prefix.
"""
all_children = []
for page in pages:
if page.type in ["package", "module"]:
if page.type == "package":
all_children += page.subpackages
all_children += page.submodules
return [
page
for page in (set(pages) - set(all_children))
if page.display and page.obj["file_path"].startswith(prefix)
]
existing = set(env.filters) | set(env.globals) | set(env.tests)
expose = ["commonpath", "relpath", "exists", "dirname", "basename"]
for func_name in expose:
path_func = getattr(os.path, func_name)
if callable(path_func) and func_name not in existing:
env.filters[func_name] = path_func
env.filters["pprint_attrs"] = pprint_attrs
env.filters["by_subpath"] = by_subpath
[docs]def autoapi_skip_members(app, what, name, obj, skip, options):
"""Skip classes imported into packages.
Removes resolve errors like these for sphinx:
.. code-block:: text
docs/autoapi/python/tk_houdini/base_hooks/node_handler_base/index.rst::
WARNING: more than one target found for cross-reference 'ParmGroup':
python.tk_houdini.utils.ParmGroup,
python.tk_houdini.utils.parm_template_wrappers.ParmGroup
See `official autoapi-skip-member documentation
<https://sphinx-autoapi.readthedocs.io/en/latest/reference/config.html#event-autoapi-skip-member>`_
"""
re_imported_classes = ["python.tk_houdini.utils"]
if what == "class":
class_module = name.rsplit(".", 1)[0]
if class_module in re_imported_classes:
print("Skipping %s" % name)
skip = True
return skip
[docs]def setup(app):
"""Register our callback to the current running Sphinx app."""
app.connect("autoapi-skip-member", autoapi_skip_members)