Skip to content

Commit 549a276

Browse files
author
Diptorup Deb
authored
Merge pull request #1332 from IntelPython/docs/api-docs
Adds API Documentation infrastructure
2 parents e998f72 + af41056 commit 549a276

File tree

18 files changed

+404
-36
lines changed

18 files changed

+404
-36
lines changed

‎docs/.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
11
apidoc
22
sources/_build
3+
source/autoapi

‎docs/Makefile

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ SPHINXOPTS ?=
77
SPHINXBUILD ?= sphinx-build
88
SOURCEDIR = ./source
99
BUILDDIR = _build
10+
AUTOAPIDIR = source/autoapi
1011

1112
# Put it first so that "make" without argument is like "make help".
1213
help:
@@ -20,4 +21,4 @@ help:
2021
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
2122

2223
clean:
23-
rm -rf "$(BUILDDIR)"
24+
rm -rf "$(BUILDDIR)" "$(AUTOAPIDIR)"

‎docs/_static/css/custom.css

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
span.summarylabel {
2+
background-color: var(--color-foreground-secondary);
3+
color: var(--color-background-secondary);
4+
font-size: 70%;
5+
padding-left: 2px;
6+
padding-right: 2px;
7+
border-radius: 3px;
8+
vertical-align: 15%;
9+
padding-bottom: 2px;
10+
filter: opacity(40%);
11+
}
12+
13+
table.summarytable {
14+
width: 100%;
15+
}

‎docs/_templates/autoapi/index.rst

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
API Reference
2+
=============
3+
4+
This page contains auto-generated API reference documentation [#f1]_.
5+
6+
.. toctree::
7+
:maxdepth: 2
8+
9+
numba_dpex/kernel_api/index
10+
11+
{% for page in pages %}
12+
{% if page.top_level_object and page.display %}
13+
{{ page.include_path }}
14+
{% endif %}
15+
{% endfor %}
16+
17+
.. [#f1] Created with `sphinx-autoapi <https://github.com/readthedocs/sphinx-autoapi>`_

‎docs/_templates/autoapi/macros.rst

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
{% macro _render_item_name(obj, sig=False) -%}
2+
:py:obj:`{{ obj.name }} <{{ obj.id }}>`
3+
{%- if sig -%}
4+
\ (
5+
{%- for arg in obj.obj.args -%}
6+
{%- if arg[0] %}{{ arg[0]|replace('*', '\*') }}{% endif -%}{{ arg[1] -}}
7+
{%- if not loop.last %}, {% endif -%}
8+
{%- endfor -%}
9+
){%- endif -%}
10+
{%- endmacro %}
11+
12+
{% macro _item(obj, sig=False, label='') %}
13+
* - {{ _render_item_name(obj, sig) }}
14+
- {% if label %}:summarylabel:`{{ label }}` {% endif %}{% if obj.summary %}{{ obj.summary }}{% else %}\-{% endif +%}
15+
{% endmacro %}
16+
17+
{% macro auto_summary(objs, title='') -%}
18+
.. list-table:: {{ title }}
19+
:header-rows: 0
20+
:widths: auto
21+
:class: summarytable
22+
23+
{% for obj in objs -%}
24+
{%- set sig = (obj.type in ['method', 'function'] and not 'property' in obj.properties) -%}
25+
26+
{%- if 'property' in obj.properties -%}
27+
{%- set label = 'prop' -%}
28+
{%- elif 'classmethod' in obj.properties -%}
29+
{%- set label = 'class' -%}
30+
{%- elif 'abstractmethod' in obj.properties -%}
31+
{%- set label = 'abc' -%}
32+
{%- elif 'staticmethod' in obj.properties -%}
33+
{%- set label = 'static' -%}
34+
{%- else -%}
35+
{%- set label = '' -%}
36+
{%- endif -%}
37+
38+
{{- _item(obj, sig=sig, label=label) -}}
39+
{%- endfor -%}
40+
41+
{% endmacro %}

‎docs/_templates/autoapi/python/attribute.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{% extends "python/data.rst" %}

‎docs/_templates/autoapi/python/class.rst

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
{% import 'macros.rst' as macros %}
2+
3+
{% if obj.display %}
4+
.. py:{{ obj.type }}:: {{ obj.short_name }}{% if obj.args %}({{ obj.args }}){% endif %}
5+
{% for (args, return_annotation) in obj.overloads %}
6+
{{ " " * (obj.type | length) }} {{ obj.short_name }}{% if args %}({{ args }}){% endif %}
7+
{% endfor %}
8+
9+
10+
{% if obj.bases %}
11+
{% if "show-inheritance" in autoapi_options %}
12+
Bases: {% for base in obj.bases %}{{ base|link_objs }}{% if not loop.last %}, {% endif %}{% endfor %}
13+
{% endif %}
14+
15+
16+
{% if "show-inheritance-diagram" in autoapi_options and obj.bases != ["object"] %}
17+
.. autoapi-inheritance-diagram:: {{ obj.obj["full_name"] }}
18+
:parts: 1
19+
{% if "private-members" in autoapi_options %}
20+
:private-bases:
21+
{% endif %}
22+
23+
{% endif %}
24+
{% endif %}
25+
{% if obj.docstring %}
26+
{{ obj.docstring|indent(3) }}
27+
{% endif %}
28+
{% if "inherited-members" in autoapi_options %}
29+
{% set visible_classes = obj.classes|selectattr("display")|list %}
30+
{% else %}
31+
{% set visible_classes = obj.classes|rejectattr("inherited")|selectattr("display")|list %}
32+
{% endif %}
33+
{% for klass in visible_classes %}
34+
{{ klass.render()|indent(3) }}
35+
{% endfor %}
36+
{% if "inherited-members" in autoapi_options %}
37+
{% set visible_attributes = obj.attributes|selectattr("display")|list %}
38+
{% else %}
39+
{% set visible_attributes = obj.attributes|rejectattr("inherited")|selectattr("display")|list %}
40+
{% endif %}
41+
{% if "inherited-members" in autoapi_options %}
42+
{% set visible_methods = obj.methods|selectattr("display")|list %}
43+
{% else %}
44+
{% set visible_methods = obj.methods|rejectattr("inherited")|selectattr("display")|list %}
45+
{% endif %}
46+
47+
{% if visible_methods or visible_attributes %}
48+
.. rubric:: Overview
49+
50+
{% set summary_methods = visible_methods|rejectattr("properties", "contains", "property")|list %}
51+
{% set summary_attributes = visible_attributes + visible_methods|selectattr("properties", "contains", "property")|list %}
52+
{% if summary_attributes %}
53+
{{ macros.auto_summary(summary_attributes, title="Attributes")|indent(3) }}
54+
{% endif %}
55+
56+
{% if summary_methods %}
57+
{{ macros.auto_summary(summary_methods, title="Methods")|indent(3) }}
58+
{% endif %}
59+
60+
.. rubric:: Members
61+
62+
{% for attribute in visible_attributes %}
63+
{{ attribute.render()|indent(3) }}
64+
{% endfor %}
65+
{% for method in visible_methods %}
66+
{{ method.render()|indent(3) }}
67+
{% endfor %}
68+
{% endif %}
69+
{% endif %}

‎docs/_templates/autoapi/python/data.rst

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
{% if obj.display %}
2+
.. py:{{ obj.type }}:: {{ obj.name }}
3+
{%- if obj.annotation is not none %}
4+
5+
:type: {%- if obj.annotation %} {{ obj.annotation }}{%- endif %}
6+
7+
{%- endif %}
8+
9+
{%- if obj.value is not none %}
10+
11+
:value: {% if obj.value is string and obj.value.splitlines()|count > 1 -%}
12+
Multiline-String
13+
14+
.. raw:: html
15+
16+
<details><summary>Show Value</summary>
17+
18+
.. code-block:: python
19+
20+
"""{{ obj.value|indent(width=8,blank=true) }}"""
21+
22+
.. raw:: html
23+
24+
</details>
25+
26+
{%- else -%}
27+
{%- if obj.value is string -%}
28+
{{ "%r" % obj.value|string|truncate(100) }}
29+
{%- else -%}
30+
{{ obj.value|string|truncate(100) }}
31+
{%- endif -%}
32+
{%- endif %}
33+
{%- endif %}
34+
35+
36+
{{ obj.docstring|indent(3) }}
37+
{% endif %}

‎docs/_templates/autoapi/python/exception.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{% extends "python/class.rst" %}

‎docs/_templates/autoapi/python/function.rst

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{% if obj.display %}
2+
.. py:function:: {{ obj.short_name }}({{ obj.args }}){% if obj.return_annotation is not none %} -> {{ obj.return_annotation }}{% endif %}
3+
4+
{% for (args, return_annotation) in obj.overloads %}
5+
{{ obj.short_name }}({{ args }}){% if return_annotation is not none %} -> {{ return_annotation }}{% endif %}
6+
7+
{% endfor %}
8+
{% for property in obj.properties %}
9+
:{{ property }}:
10+
{% endfor %}
11+
12+
{% if obj.docstring %}
13+
{{ obj.docstring|indent(3) }}
14+
{% endif %}
15+
{% endif %}

0 commit comments

Comments
 (0)