conf.py

#
# 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 datetime import datetime
from urllib.parse import urljoin

from sphinx.ext.autodoc import FunctionDocumenter
from sphinx.ext.napoleon import NumpyDocstring, docstring

from dpnp.dpnp_algo.dpnp_elementwise_common import (
    DPNPBinaryFunc,
    DPNPBinaryFuncOutKw,
    DPNPBinaryTwoOutputsFunc,
    DPNPUnaryFunc,
    DPNPUnaryTwoOutputsFunc,
)

try:
    import comparison_generator
except ImportError:
    # 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 os
    import sys

    sys.path.insert(0, os.path.abspath("."))
    import comparison_generator


# Generate comparison table.
with open("reference/comparison_table.rst.inc", "w") as fd:
    fd.write(comparison_generator.generate())

import dpnp

# -- Project information -----------------------------------------------------

project = "Data Parallel Extension for NumPy"
year = datetime.now().year
copyright = f"2020-{year}, Intel Corporation"
author = "Intel"

version = dpnp.__version__.strip(".dirty")
# The full version, including alpha/beta/rc tags
release = dpnp.__version__.strip(".dirty")


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

# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'

# 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.viewcode",
    "sphinx.ext.githubpages",
    "sphinx.ext.intersphinx",
    "sphinx.ext.napoleon",
    "sphinx.ext.autodoc",
    "sphinx.ext.autosummary",
    "sphinxcontrib.googleanalytics",
    "sphinxcontrib.spelling",
]

googleanalytics_id = "G-554F8VNE28"
googleanalytics_enabled = True

# Enable a misspelling as a sphinx warning
spelling_warning = True

# Define a list of words known to be spelled correctly
spelling_word_list_filename = "known_words.txt"

# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]

# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = ".rst"

# The master toctree document.
master_doc = "index"

# 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.
language = "en"

# 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 .
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = "sphinx"


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

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
# html_theme = 'alabaster'
html_theme = "sphinx_rtd_theme"
html_theme_options = {
    "sidebarwidth": 30,
    "nosidebar": False,
}

# 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 = {}

# 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 = []

# 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 = {}
html_sidebars = {
    "**": [
        "globaltoc.html",
        "relations.html",
        "sourcelink.html",
        "searchbox.html",
    ]
}


# -- Options for HTMLHelp output ---------------------------------------------

# Output file base name for HTML help builder.
htmlhelp_basename = "dpnpdoc"


# -- Options for LaTeX output ------------------------------------------------

latex_elements = {
    # The paper size ('letterpaper' or 'a4paper').
    #
    # 'papersize': 'letterpaper',
    # The font size ('10pt', '11pt' or '12pt').
    #
    # 'pointsize': '10pt',
    # Additional stuff for the LaTeX preamble.
    #
    # 'preamble': '',
    # Latex figure (float) alignment
    #
    # 'figure_align': 'htbp',
}

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
#  author, documentclass [howto, manual, or own class]).
latex_documents = [
    (master_doc, "dpnp.tex", "dpnp Documentation", "Intel", "manual"),
]


# -- Options for manual page output ------------------------------------------

# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [(master_doc, "dpnp", "dpnp Documentation", [author], 1)]


# -- Options for Texinfo output ----------------------------------------------

# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
#  dir menu entry, description, category)
texinfo_documents = [
    (
        master_doc,
        "dpnp",
        "dpnp Documentation",
        author,
        "dpnp",
        "One line description of project.",
        "Miscellaneous",
    ),
]


# -- Extension configuration -------------------------------------------------


# -- Options for todo extension ----------------------------------------------
def _can_document_member(member, *args, **kwargs):
    if isinstance(
        member,
        (
            DPNPBinaryFunc,
            DPNPBinaryFuncOutKw,
            DPNPBinaryTwoOutputsFunc,
            DPNPUnaryFunc,
            DPNPUnaryTwoOutputsFunc,
        ),
    ):
        return True
    return orig(member, *args, **kwargs)


documenter = FunctionDocumenter
orig = documenter.can_document_member
documenter.can_document_member = _can_document_member

autosummary_generate = True

_DPCTL_021_BASE = "https://intelpython.github.io/dpctl/0.21.1/"
_DPCTL_021_INV = urljoin(_DPCTL_021_BASE, "objects.inv")

intersphinx_mapping = {
    "python": ("https://docs.python.org/3/", None),
    "numpy": ("https://numpy.org/doc/stable/", None),
    "scipy": ("https://docs.scipy.org/doc/scipy/reference/", None),
    "dpctl": ("https://intelpython.github.io/dpctl/latest/", None),
    "cupy": ("https://docs.cupy.dev/en/stable/", None),
}

# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True

# Napoleon settings
napoleon_use_ivar = True
napoleon_include_special_with_doc = True
napoleon_custom_sections = ["limitations"]


# Napoleon extension can't properly render "Returns" section in case of
# namedtuple as a return type. That patch proposes to extend the parse logic
# which allows text in a header of "Returns" section.
def _parse_returns_section_patched(self, section: str) -> list[str]:
    fields = self._consume_returns_section()
    multi = len(fields) > 1
    use_rtype = False if multi else self._config.napoleon_use_rtype
    lines: list[str] = []
    header: list[str] = []
    is_logged_header = False

    for _name, _type, _desc in fields:
        # self._consume_returns_section() stores the header block
        # into `_type` argument, while `_name` has to be empty string and
        # `_desc` has to be empty list of strings
        if _name == "" and (not _desc or len(_desc) == 1 and _desc[0] == ""):
            if not is_logged_header:
                docstring.logger.info(
                    "parse a header block of 'Returns' section",
                    location=self._get_location(),
                )
                is_logged_header = True

            # build a list with lines of the header block
            header.extend([_type])
            continue

        if use_rtype:
            field = self._format_field(_name, "", _desc)
        else:
            field = self._format_field(_name, _type, _desc)

        if multi:
            if lines:
                lines.extend(self._format_block("          * ", field))
            else:
                if header:
                    # add the header block + the 1st parameter stored in `field`
                    lines.extend([":returns:", ""])
                    lines.extend(self._format_block(" " * 4, header))
                    lines.extend(self._format_block("          * ", field))
                else:
                    lines.extend(self._format_block(":returns: * ", field))
        else:
            if any(field):  # only add :returns: if there's something to say
                lines.extend(self._format_block(":returns: ", field))
            if _type and use_rtype:
                lines.extend([f":rtype: {_type}", ""])
    if lines and lines[-1]:
        lines.append("")
    return lines


NumpyDocstring._parse_returns_section = _parse_returns_section_patched


# TODO: Remove once dpnp.tensor docs are generated in dpnp
def _load_dpctl_tensor_inventory(app):
    """Load dpctl 0.21.1 inventory for dpnp.tensor fallback only."""
    from sphinx.ext.intersphinx import fetch_inventory
    from sphinx.util import logging

    logger = logging.getLogger(__name__)

    try:
        inv = fetch_inventory(app, _DPCTL_021_BASE, _DPCTL_021_INV)
    except Exception as exc:
        logger.warning(
            "Failed to load dpctl 0.21.1 inventory from %s: %s",
            _DPCTL_021_INV,
            exc,
        )
        inv = {}

    app.builder.env._dpctl_tensor_021_inventory = inv


# TODO: Remove once dpnp.tensor docs are generated in dpnp
def _resolve_dpnp_tensor_refs(app, env, node, contnode):
    """Resolve dpnp.tensor.* references to dpctl 0.21.1 documentation.

    This temporary workaround is needed because dpnp.tensor documentation
    is not generated yet, while the corresponding API is still documented
    in dpctl 0.21.1.
    """
    from docutils import nodes as docutils_nodes

    target = node.get("reftarget", "")
    if not target.startswith("dpnp.tensor"):
        return None

    dpctl_target = target.replace("dpnp.tensor", "dpctl.tensor", 1)
    dpctl_tensor_inv = getattr(env, "_dpctl_tensor_021_inventory", {})

    for _objtype, objects in dpctl_tensor_inv.items():
        if dpctl_target not in objects:
            continue

        item = objects[dpctl_target]
        location = item.uri
        if location.endswith("$"):
            location = location[:-1] + dpctl_target

        refuri = urljoin(_DPCTL_021_BASE, location)
        newnode = docutils_nodes.reference(
            "", "", internal=False, refuri=refuri
        )
        newnode += contnode.deepcopy()
        return newnode

    return None


def setup(app):
    app.connect("builder-inited", _load_dpctl_tensor_inventory, priority=400)
    app.connect("missing-reference", _resolve_dpnp_tensor_refs, priority=400)