From af41056ce06ac525fccc9f3490ee2d92bdac967b Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Tue, 13 Feb 2024 17:26:58 -0600 Subject: [PATCH] Initial auto-api setup. --- docs/.gitignore | 1 + docs/Makefile | 3 +- docs/_static/css/custom.css | 15 +++ docs/_templates/autoapi/index.rst | 17 +++ docs/_templates/autoapi/macros.rst | 41 +++++++ docs/_templates/autoapi/python/attribute.rst | 1 + docs/_templates/autoapi/python/class.rst | 69 ++++++++++++ docs/_templates/autoapi/python/data.rst | 37 ++++++ docs/_templates/autoapi/python/exception.rst | 1 + docs/_templates/autoapi/python/function.rst | 15 +++ docs/_templates/autoapi/python/method.rst | 19 ++++ docs/_templates/autoapi/python/module.rst | 112 +++++++++++++++++++ docs/_templates/autoapi/python/package.rst | 1 + docs/_templates/autoapi/python/property.rst | 15 +++ docs/source/api_reference/index.rst | 8 -- docs/source/conf.py | 81 +++++++++----- docs/source/index.rst | 2 +- environment/docs.yml | 2 + 18 files changed, 404 insertions(+), 36 deletions(-) create mode 100644 docs/_static/css/custom.css create mode 100644 docs/_templates/autoapi/index.rst create mode 100644 docs/_templates/autoapi/macros.rst create mode 100644 docs/_templates/autoapi/python/attribute.rst create mode 100644 docs/_templates/autoapi/python/class.rst create mode 100644 docs/_templates/autoapi/python/data.rst create mode 100644 docs/_templates/autoapi/python/exception.rst create mode 100644 docs/_templates/autoapi/python/function.rst create mode 100644 docs/_templates/autoapi/python/method.rst create mode 100644 docs/_templates/autoapi/python/module.rst create mode 100644 docs/_templates/autoapi/python/package.rst create mode 100644 docs/_templates/autoapi/python/property.rst delete mode 100644 docs/source/api_reference/index.rst diff --git a/docs/.gitignore b/docs/.gitignore index 5c490088af..c221eeaac0 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,2 +1,3 @@ apidoc sources/_build +source/autoapi diff --git a/docs/Makefile b/docs/Makefile index 1ed4090504..e912e4ca8e 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -7,6 +7,7 @@ SPHINXOPTS ?= SPHINXBUILD ?= sphinx-build SOURCEDIR = ./source BUILDDIR = _build +AUTOAPIDIR = source/autoapi # Put it first so that "make" without argument is like "make help". help: @@ -20,4 +21,4 @@ help: @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) clean: - rm -rf "$(BUILDDIR)" + rm -rf "$(BUILDDIR)" "$(AUTOAPIDIR)" diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css new file mode 100644 index 0000000000..889b915047 --- /dev/null +++ b/docs/_static/css/custom.css @@ -0,0 +1,15 @@ +span.summarylabel { + background-color: var(--color-foreground-secondary); + color: var(--color-background-secondary); + font-size: 70%; + padding-left: 2px; + padding-right: 2px; + border-radius: 3px; + vertical-align: 15%; + padding-bottom: 2px; + filter: opacity(40%); +} + +table.summarytable { + width: 100%; +} diff --git a/docs/_templates/autoapi/index.rst b/docs/_templates/autoapi/index.rst new file mode 100644 index 0000000000..1af3e006b2 --- /dev/null +++ b/docs/_templates/autoapi/index.rst @@ -0,0 +1,17 @@ +API Reference +============= + +This page contains auto-generated API reference documentation [#f1]_. + +.. toctree:: + :maxdepth: 2 + + numba_dpex/kernel_api/index + + {% for page in pages %} + {% if page.top_level_object and page.display %} + {{ page.include_path }} + {% endif %} + {% endfor %} + +.. [#f1] Created with `sphinx-autoapi `_ diff --git a/docs/_templates/autoapi/macros.rst b/docs/_templates/autoapi/macros.rst new file mode 100644 index 0000000000..9703b9d2db --- /dev/null +++ b/docs/_templates/autoapi/macros.rst @@ -0,0 +1,41 @@ +{% macro _render_item_name(obj, sig=False) -%} +:py:obj:`{{ obj.name }} <{{ obj.id }}>` + {%- if sig -%} + \ ( + {%- for arg in obj.obj.args -%} + {%- if arg[0] %}{{ arg[0]|replace('*', '\*') }}{% endif -%}{{ arg[1] -}} + {%- if not loop.last %}, {% endif -%} + {%- endfor -%} + ){%- endif -%} +{%- endmacro %} + +{% macro _item(obj, sig=False, label='') %} + * - {{ _render_item_name(obj, sig) }} + - {% if label %}:summarylabel:`{{ label }}` {% endif %}{% if obj.summary %}{{ obj.summary }}{% else %}\-{% endif +%} +{% endmacro %} + +{% macro auto_summary(objs, title='') -%} +.. list-table:: {{ title }} + :header-rows: 0 + :widths: auto + :class: summarytable + + {% for obj in objs -%} + {%- set sig = (obj.type in ['method', 'function'] and not 'property' in obj.properties) -%} + + {%- if 'property' in obj.properties -%} + {%- set label = 'prop' -%} + {%- elif 'classmethod' in obj.properties -%} + {%- set label = 'class' -%} + {%- elif 'abstractmethod' in obj.properties -%} + {%- set label = 'abc' -%} + {%- elif 'staticmethod' in obj.properties -%} + {%- set label = 'static' -%} + {%- else -%} + {%- set label = '' -%} + {%- endif -%} + + {{- _item(obj, sig=sig, label=label) -}} + {%- endfor -%} + +{% endmacro %} diff --git a/docs/_templates/autoapi/python/attribute.rst b/docs/_templates/autoapi/python/attribute.rst new file mode 100644 index 0000000000..ebaba555ad --- /dev/null +++ b/docs/_templates/autoapi/python/attribute.rst @@ -0,0 +1 @@ +{% extends "python/data.rst" %} diff --git a/docs/_templates/autoapi/python/class.rst b/docs/_templates/autoapi/python/class.rst new file mode 100644 index 0000000000..ab998efa5e --- /dev/null +++ b/docs/_templates/autoapi/python/class.rst @@ -0,0 +1,69 @@ +{% import 'macros.rst' as macros %} + +{% if obj.display %} +.. py:{{ obj.type }}:: {{ obj.short_name }}{% if obj.args %}({{ obj.args }}){% endif %} +{% for (args, return_annotation) in obj.overloads %} + {{ " " * (obj.type | length) }} {{ obj.short_name }}{% if args %}({{ args }}){% endif %} +{% endfor %} + + + {% if obj.bases %} + {% if "show-inheritance" in autoapi_options %} + Bases: {% for base in obj.bases %}{{ base|link_objs }}{% if not loop.last %}, {% endif %}{% endfor %} + {% endif %} + + + {% if "show-inheritance-diagram" in autoapi_options and obj.bases != ["object"] %} + .. autoapi-inheritance-diagram:: {{ obj.obj["full_name"] }} + :parts: 1 + {% if "private-members" in autoapi_options %} + :private-bases: + {% endif %} + + {% endif %} + {% endif %} + {% if obj.docstring %} + {{ obj.docstring|indent(3) }} + {% endif %} + {% if "inherited-members" in autoapi_options %} + {% set visible_classes = obj.classes|selectattr("display")|list %} + {% else %} + {% set visible_classes = obj.classes|rejectattr("inherited")|selectattr("display")|list %} + {% endif %} + {% for klass in visible_classes %} + {{ klass.render()|indent(3) }} + {% endfor %} + {% if "inherited-members" in autoapi_options %} + {% set visible_attributes = obj.attributes|selectattr("display")|list %} + {% else %} + {% set visible_attributes = obj.attributes|rejectattr("inherited")|selectattr("display")|list %} + {% endif %} + {% if "inherited-members" in autoapi_options %} + {% set visible_methods = obj.methods|selectattr("display")|list %} + {% else %} + {% set visible_methods = obj.methods|rejectattr("inherited")|selectattr("display")|list %} + {% endif %} + + {% if visible_methods or visible_attributes %} + .. rubric:: Overview + + {% set summary_methods = visible_methods|rejectattr("properties", "contains", "property")|list %} + {% set summary_attributes = visible_attributes + visible_methods|selectattr("properties", "contains", "property")|list %} + {% if summary_attributes %} + {{ macros.auto_summary(summary_attributes, title="Attributes")|indent(3) }} + {% endif %} + + {% if summary_methods %} + {{ macros.auto_summary(summary_methods, title="Methods")|indent(3) }} + {% endif %} + + .. rubric:: Members + + {% for attribute in visible_attributes %} + {{ attribute.render()|indent(3) }} + {% endfor %} + {% for method in visible_methods %} + {{ method.render()|indent(3) }} + {% endfor %} + {% endif %} +{% endif %} diff --git a/docs/_templates/autoapi/python/data.rst b/docs/_templates/autoapi/python/data.rst new file mode 100644 index 0000000000..3d12b2d0c7 --- /dev/null +++ b/docs/_templates/autoapi/python/data.rst @@ -0,0 +1,37 @@ +{% if obj.display %} +.. py:{{ obj.type }}:: {{ obj.name }} + {%- if obj.annotation is not none %} + + :type: {%- if obj.annotation %} {{ obj.annotation }}{%- endif %} + + {%- endif %} + + {%- if obj.value is not none %} + + :value: {% if obj.value is string and obj.value.splitlines()|count > 1 -%} + Multiline-String + + .. raw:: html + +
Show Value + + .. code-block:: python + + """{{ obj.value|indent(width=8,blank=true) }}""" + + .. raw:: html + +
+ + {%- else -%} + {%- if obj.value is string -%} + {{ "%r" % obj.value|string|truncate(100) }} + {%- else -%} + {{ obj.value|string|truncate(100) }} + {%- endif -%} + {%- endif %} + {%- endif %} + + + {{ obj.docstring|indent(3) }} +{% endif %} diff --git a/docs/_templates/autoapi/python/exception.rst b/docs/_templates/autoapi/python/exception.rst new file mode 100644 index 0000000000..92f3d38fd5 --- /dev/null +++ b/docs/_templates/autoapi/python/exception.rst @@ -0,0 +1 @@ +{% extends "python/class.rst" %} diff --git a/docs/_templates/autoapi/python/function.rst b/docs/_templates/autoapi/python/function.rst new file mode 100644 index 0000000000..778ba9a883 --- /dev/null +++ b/docs/_templates/autoapi/python/function.rst @@ -0,0 +1,15 @@ +{% if obj.display %} +.. py:function:: {{ obj.short_name }}({{ obj.args }}){% if obj.return_annotation is not none %} -> {{ obj.return_annotation }}{% endif %} + +{% for (args, return_annotation) in obj.overloads %} + {{ obj.short_name }}({{ args }}){% if return_annotation is not none %} -> {{ return_annotation }}{% endif %} + +{% endfor %} + {% for property in obj.properties %} + :{{ property }}: + {% endfor %} + + {% if obj.docstring %} + {{ obj.docstring|indent(3) }} + {% endif %} +{% endif %} diff --git a/docs/_templates/autoapi/python/method.rst b/docs/_templates/autoapi/python/method.rst new file mode 100644 index 0000000000..f50a1bd6ee --- /dev/null +++ b/docs/_templates/autoapi/python/method.rst @@ -0,0 +1,19 @@ +{%- if obj.display %} +.. py:method:: {{ obj.short_name }}({{ obj.args }}){% if obj.return_annotation is not none %} -> {{ obj.return_annotation }}{% endif %} + +{% for (args, return_annotation) in obj.overloads %} + {{ obj.short_name }}({{ args }}){% if return_annotation is not none %} -> {{ return_annotation }}{% endif %} + +{% endfor %} + {% if obj.properties %} + {% for property in obj.properties %} + :{{ property }}: + {% endfor %} + + {% else %} + + {% endif %} + {% if obj.docstring %} + {{ obj.docstring|indent(3) }} + {% endif %} +{% endif %} diff --git a/docs/_templates/autoapi/python/module.rst b/docs/_templates/autoapi/python/module.rst new file mode 100644 index 0000000000..32143c3957 --- /dev/null +++ b/docs/_templates/autoapi/python/module.rst @@ -0,0 +1,112 @@ +{% import 'macros.rst' as macros %} + +{% if not obj.display %} +:orphan: + +{% endif %} +{{ obj.name }} +{{ "=" * obj.name|length }} + +.. py:module:: {{ obj.name }} + +{% if obj.docstring %} +.. autoapi-nested-parse:: + + {{ obj.docstring|indent(3) }} + +{% endif %} + +{% block subpackages %} +{% set visible_subpackages = obj.subpackages|selectattr("display")|list %} +{% if visible_subpackages %} +Subpackages +----------- +.. toctree:: + :titlesonly: + :maxdepth: 3 + +{% for subpackage in visible_subpackages %} + {{ subpackage.short_name }}/index.rst +{% endfor %} + + +{% endif %} +{% endblock %} +{% block submodules %} +{% set visible_submodules = obj.submodules|selectattr("display")|list %} +{% if visible_submodules %} +Submodules +---------- +.. toctree:: + :titlesonly: + :maxdepth: 1 + +{% for submodule in visible_submodules %} + {{ submodule.short_name }}/index.rst +{% endfor %} + + +{% endif %} +{% endblock %} +{% block content %} +{% if obj.all is not none %} +{% set visible_children = obj.children|selectattr("display")|selectattr("short_name", "in", obj.all)|list %} +{% elif obj.type is equalto("package") %} +{% set visible_children = obj.children|selectattr("display")|list %} +{% else %} +{% set visible_children = obj.children|selectattr("display")|rejectattr("imported")|list %} +{% endif %} +{% if visible_children %} +Overview +-------- + +{% set visible_classes = visible_children|selectattr("type", "equalto", "class")|list %} +{% set visible_functions = visible_children|selectattr("type", "equalto", "function")|list %} +{% set visible_attributes = visible_children|selectattr("type", "equalto", "data")|list %} +{% if "show-module-summary" in autoapi_options and (visible_classes or visible_functions) %} +{% block classes scoped %} +{% if visible_classes %} +{{ macros.auto_summary(visible_classes, title="Classes") }} +{% endif %} +{% endblock %} + +{% block functions scoped %} +{% if visible_functions %} +{{ macros.auto_summary(visible_functions, title="Function") }} +{% endif %} +{% endblock %} + +{% block attributes scoped %} +{% if visible_attributes %} +{{ macros.auto_summary(visible_attributes, title="Attributes") }} +{% endif %} +{% endblock %} +{% endif %} + +{% if visible_classes %} +Classes +------- +{% for obj_item in visible_classes %} +{{ obj_item.render()|indent(0) }} +{% endfor %} +{% endif %} + +{% if visible_functions %} +Functions +--------- +{% for obj_item in visible_functions %} +{{ obj_item.render()|indent(0) }} +{% endfor %} +{% endif %} + +{% if visible_attributes %} +Attributes +---------- +{% for obj_item in visible_attributes %} +{{ obj_item.render()|indent(0) }} +{% endfor %} +{% endif %} + + +{% endif %} +{% endblock %} diff --git a/docs/_templates/autoapi/python/package.rst b/docs/_templates/autoapi/python/package.rst new file mode 100644 index 0000000000..fb9a64965e --- /dev/null +++ b/docs/_templates/autoapi/python/package.rst @@ -0,0 +1 @@ +{% extends "python/module.rst" %} diff --git a/docs/_templates/autoapi/python/property.rst b/docs/_templates/autoapi/python/property.rst new file mode 100644 index 0000000000..70af24236f --- /dev/null +++ b/docs/_templates/autoapi/python/property.rst @@ -0,0 +1,15 @@ +{%- if obj.display %} +.. py:property:: {{ obj.short_name }} + {% if obj.annotation %} + :type: {{ obj.annotation }} + {% endif %} + {% if obj.properties %} + {% for property in obj.properties %} + :{{ property }}: + {% endfor %} + {% endif %} + + {% if obj.docstring %} + {{ obj.docstring|indent(3) }} + {% endif %} +{% endif %} diff --git a/docs/source/api_reference/index.rst b/docs/source/api_reference/index.rst deleted file mode 100644 index 728caaabcf..0000000000 --- a/docs/source/api_reference/index.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. _index: -.. include:: ./../ext_links.txt - - -API Reference -============= - -Coming soon diff --git a/docs/source/conf.py b/docs/source/conf.py index 60d42b9b98..1e723da1e8 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,28 +1,6 @@ -# ***************************************************************************** -# Copyright (c) 2022, Intel Corporation All rights reserved. +# SPDX-FileCopyrightText: 2020 - 2024 Intel Corporation # -# Redistribution and use in source and binary forms, with or without -# modification, are permitted provided that the following conditions are met: -# -# Redistributions of source code must retain the above copyright notice, -# this list of conditions and the following disclaimer. -# -# 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. -# -# 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. -# ***************************************************************************** +# SPDX-License-Identifier: Apache-2.0 # coding: utf-8 # Configuration file for the Sphinx documentation builder. @@ -32,7 +10,7 @@ # -- Project information ----------------------------------------------------- project = "numba-dpex" -copyright = "2020-2023, Intel Corporation" +copyright = "2020-2024, Intel Corporation" author = "Intel Corporation" # The full version, including alpha/beta/rc tags @@ -53,6 +31,7 @@ "sphinxcontrib.programoutput", "sphinxcontrib.googleanalytics", "myst_parser", + "autoapi.extension", ] # Add any paths that contain templates here, relative to this directory. @@ -70,7 +49,8 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = "pydata_sphinx_theme" +# html_theme = "pydata_sphinx_theme" +html_theme = "furo" html_theme_options = { "icon_links": [ @@ -137,3 +117,52 @@ # -- Prepend module name to an object name or not ----------------------------------- add_module_names = False + +# -- Auto API configurations --------------------------------------------------- + + +# def skip_util_classes(app, what, name, obj, skip, options): +# if what == "module" and "experimental" in name: +# if what == "module" and "decorators" not in name: +# skip = True +# return skip + + +# def setup(sphinx): +# sphinx.connect("autoapi-skip-member", skip_util_classes) + + +autoapi_dirs = ["../../numba_dpex/kernel_api"] +autoapi_type = "python" + +autoapi_template_dir = "_templates/autoapi" + +autoapi_options = [ + "members", + "undoc-members", + "show-inheritance", + "show-module-summary", + "imported-members", +] + +autoapi_keep_files = True +autodoc_typehints = "signature" + +rst_prolog = """ +.. role:: summarylabel +""" + +html_css_files = [ + "css/custom.css", +] + + +def contains(seq, item): + return item in seq + + +def prepare_jinja_env(jinja_env) -> None: + jinja_env.tests["contains"] = contains + + +autoapi_prepare_jinja_env = prepare_jinja_env diff --git a/docs/source/index.rst b/docs/source/index.rst index c8ce20c0c9..871f23790f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -46,7 +46,7 @@ Data Parallel Extension for Numba* overview getting_started user_guide/index - api_reference/index + autoapi/index .. toctree:: :maxdepth: 2 diff --git a/environment/docs.yml b/environment/docs.yml index 4daf1c16b0..48b96f9e3f 100644 --- a/environment/docs.yml +++ b/environment/docs.yml @@ -19,6 +19,7 @@ dependencies: - pip - pip: - sphinx + - sphinx-autoapi - autodoc # there is no conda package - recommonmark - sphinx-rtd-theme @@ -27,3 +28,4 @@ dependencies: - sphinxcontrib.programoutput - pydata-sphinx-theme - myst-parser + - furo