Adds API Documentation infrastructure

docs/.gitignore

@@ -1,2 +1,3 @@
 apidoc
 sources/_build
+source/autoapi

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)"

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%;
+}

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 <https://github.com/readthedocs/sphinx-autoapi>`_

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 %}

docs/_templates/autoapi/python/attribute.rst

@@ -0,0 +1 @@
+{% extends "python/data.rst" %}

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 %}

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
+
+        <details><summary>Show Value</summary>
+
+    .. code-block:: python
+
+        """{{ obj.value|indent(width=8,blank=true) }}"""
+
+    .. raw:: html
+
+        </details>
+
+            {%- 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 %}

docs/_templates/autoapi/python/exception.rst

@@ -0,0 +1 @@
+{% extends "python/class.rst" %}

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 %}

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 %}

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 %}

docs/_templates/autoapi/python/package.rst

@@ -0,0 +1 @@
+{% extends "python/module.rst" %}

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 %}