Skip to content

Commit f513218

Browse files
jorgepilotoRevathyvenugopal162RobPasMue
authored
feat: add API templates for sphinx-autoapi (#278)
Co-authored-by: Revathyvenugopal162 <[email protected]> Co-authored-by: Revathy Venugopal <[email protected]> Co-authored-by: Roberto Pastor Muela <[email protected]>
1 parent 5f96257 commit f513218

File tree

6 files changed

+488
-1
lines changed

6 files changed

+488
-1
lines changed

‎.pre-commit-config.yaml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,3 +50,4 @@ repos:
5050
hooks:
5151
- id: blacken-docs
5252
additional_dependencies: [black==23.7.0]
53+
exclude: 'src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/'

‎src/ansys_sphinx_theme/__init__.py

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
"""This is the ansys-sphinx-theme module."""
22
import logging
3+
import os
34
import pathlib
45
from typing import Any, Dict
56

@@ -21,6 +22,7 @@
2122
JS_PATH = STATIC_PATH / "js"
2223
CSS_PATH = STYLE_PATH / "ansys_sphinx_theme.css"
2324
TEMPLATES_PATH = THEME_PATH / "_templates"
25+
AUTOAPI_TEMPLATES_PATH = TEMPLATES_PATH / "autoapi"
2426
JS_FILE = JS_PATH / "table.js"
2527

2628
# make logo paths available
@@ -66,6 +68,25 @@ def get_version_match(semver: str) -> str:
6668
return ".".join([major, minor])
6769

6870

71+
def get_autoapi_templates_dir_relative_path(path: pathlib.Path) -> str:
72+
"""Return a string representing the relative path for autoapi templates.
73+
74+
Parameters
75+
----------
76+
path : pathlib.Path
77+
Path to the desired file.
78+
79+
Returns
80+
-------
81+
str
82+
A string rerpesenting the relative path to the autoapi templates.
83+
84+
"""
85+
return os.path.relpath(
86+
str(AUTOAPI_TEMPLATES_PATH.absolute()), start=str(path.parent.absolute())
87+
)
88+
89+
6990
def convert_version_to_pymeilisearch(semver: str) -> str:
7091
"""Convert a semantic version number to pymeilisearch-compatible format.
7192
@@ -187,7 +208,7 @@ def fix_edit_link_page(link: str) -> str:
187208
logging.debug(f"An error occurred: {e}") # Log the exception as debug info
188209
return link
189210

190-
elif "autoapi" in pagename:
211+
elif pagename in ["autoapi", "api"]:
191212
for obj_node in list(doctree.findall(addnodes.desc)):
192213
domain = obj_node.get("domain")
193214
if domain != "py":

‎src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/autoapi/index.rst

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
API reference
2+
=============
3+
4+
This section describes {{ project_name }} endpoints, their capabilities, and how
5+
to interact with them programmatically.
6+
7+
.. toctree::
8+
:titlesonly:
9+
:maxdepth: 3
10+
11+
{% for page in pages %}
12+
{% if (page.top_level_object or page.name.split('.') | length == 3) and page.display %}
13+
🖿 {{ page.name }}<{{ page.include_path }}>
14+
{% endif %}
15+
{% endfor %}

‎src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/autoapi/python/class.rst

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
{# ------------------------- Begin macros definition ----------------------- #}
2+
3+
{% macro tab_item_from_objects_list(objects_list, title="") -%}
4+
5+
.. tab-item:: {{ title }}
6+
7+
.. list-table::
8+
:header-rows: 0
9+
:widths: auto
10+
11+
{% for obj in objects_list %}
12+
* - :py:attr:`~{{ obj.name }}`
13+
- {{ obj.summary }}
14+
{% endfor %}
15+
{%- endmacro %}
16+
17+
{# --------------------------- End macros definition ----------------------- #}
18+
19+
{% if obj.display %}
20+
21+
{% if render_in_single_page and obj["type"] in render_in_single_page %}
22+
{{ obj.short_name }}
23+
{{"=" * obj.name|length }}
24+
{% endif %}
25+
26+
.. py:{{ obj["type"] }}:: {{ obj["short_name"] }}{% if obj["args"] %}({{ obj["args"] }}){% endif %}
27+
28+
{% if render_in_single_page and obj["type"] in render_in_single_page %}
29+
:canonical: {{ obj["obj"]["full_name"] }}
30+
{% endif %}
31+
32+
{% for (args, return_annotation) in obj.overloads %}
33+
{{ " " * (obj.type | length) }} {{ obj.short_name }}{% if args %}({{ args }}){% endif %}
34+
{% endfor %}
35+
36+
37+
{% if obj.bases %}
38+
{% if "show-inheritance" in autoapi_options %}
39+
Bases: {% for base in obj.bases %}{{ base|link_objs }}{% if not loop.last %}, {% endif %}{% endfor %}
40+
{% endif %}
41+
42+
{% if "show-inheritance-diagram" in autoapi_options and obj.bases != ["object"] %}
43+
.. autoapi-inheritance-diagram:: {{ obj.obj["full_name"] }}
44+
:parts: 1
45+
{% if "private-members" in autoapi_options %}
46+
:private-bases:
47+
{% endif %}
48+
49+
{% endif %}
50+
{% endif %}
51+
52+
{% if obj.docstring -%}
53+
{{ obj.summary|indent(3) }}
54+
{% endif %}
55+
56+
{% if "inherited-members" in autoapi_options %}
57+
{% set visible_classes = obj.classes|selectattr("display")|list %}
58+
{% else %}
59+
{% set visible_classes = obj.classes|rejectattr("inherited")|selectattr("display")|list %}
60+
{% endif %}
61+
62+
{% for klass in visible_classes %}
63+
{{ klass.render()|indent(3) }}
64+
{% endfor %}
65+
66+
{% if "inherited-members" in autoapi_options %}
67+
{% set visible_properties = obj.properties|selectattr("display")|list %}
68+
{% else %}
69+
{% set visible_properties = obj.properties|rejectattr("inherited")|selectattr("display")|list %}
70+
{% endif %}
71+
72+
{% if "inherited-members" in autoapi_options %}
73+
{% set visible_attributes = obj.attributes|selectattr("display")|list %}
74+
{% else %}
75+
{% set visible_attributes = obj.attributes|rejectattr("inherited")|selectattr("display")|list %}
76+
{% endif %}
77+
78+
{% if "inherited-members" in autoapi_options %}
79+
{% set all_visible_methods = obj.methods|selectattr("display")|list %}
80+
{% else %}
81+
{% set all_visible_methods = obj.methods|rejectattr("inherited")|selectattr("display")|list %}
82+
{% endif %}
83+
84+
{% set visible_abstract_methods = [] %}
85+
{% set visible_constructor_methods = [] %}
86+
{% set visible_instance_methods = [] %}
87+
{% set visible_special_methods = [] %}
88+
{% set visible_static_methods = [] %}
89+
90+
{% for element in all_visible_methods %}
91+
{% if "abstractmethod" in element.properties %}
92+
{% set _ = visible_abstract_methods.append(element) %}
93+
94+
{% elif "staticmethod" in element.properties %}
95+
{% set _ = visible_static_methods.append(element) %}
96+
97+
{% elif "classmethod" in element.properties or element.name in ["__new__", "__init__"] %}
98+
{% set _ = visible_constructor_methods.append(element) %}
99+
100+
{% elif element.name.startswith("__") and element.name.endswith("__") and element.name not in ["__new__", "__init__"] %}
101+
{% set _ = visible_special_methods.append(element) %}
102+
103+
{% else %}
104+
{% set _ = visible_instance_methods.append(element) %}
105+
106+
{% endif %}
107+
{% endfor %}
108+
109+
110+
{% set class_objects = visible_properties + visible_attributes + all_visible_methods %}
111+
112+
{# ------------------------ Begin tabset definition ----------------------- #}
113+
114+
{% if class_objects %}
115+
116+
{% if render_in_single_page and obj["type"] in render_in_single_page %}
117+
Overview
118+
--------
119+
.. py:currentmodule:: {{ obj.short_name }}
120+
{% endif %}
121+
.. tab-set::
122+
123+
{% if visible_abstract_methods %}
124+
{{ tab_item_from_objects_list(visible_abstract_methods, "Abstract methods") }}
125+
{% endif %}
126+
127+
{% if visible_constructor_methods %}
128+
{{ tab_item_from_objects_list(visible_constructor_methods, "Constructors") }}
129+
{% endif %}
130+
131+
{% if visible_instance_methods %}
132+
{{ tab_item_from_objects_list(visible_instance_methods, "Methods") }}
133+
{% endif %}
134+
135+
{% if visible_properties %}
136+
{{ tab_item_from_objects_list(visible_properties, "Properties") }}
137+
{% endif %}
138+
139+
{% if visible_attributes %}
140+
{{ tab_item_from_objects_list(visible_attributes, "Attributes") }}
141+
{% endif %}
142+
143+
{% if visible_static_methods %}
144+
{{ tab_item_from_objects_list(visible_static_methods, "Static methods") }}
145+
{% endif %}
146+
147+
{% if visible_special_methods %}
148+
{{ tab_item_from_objects_list(visible_special_methods, "Special methods") }}
149+
{% endif %}
150+
151+
{% endif %}
152+
{% endif %}
153+
{# ---------------------- End class tabset -------------------- #}
154+
{# ---------------------- Begin class datails -------------------- #}
155+
156+
Import detail
157+
-------------
158+
{% set split_parts = obj.obj["full_name"].split('.') %}
159+
{% set joined_parts = '.'.join(split_parts[:-1]) %}
160+
161+
.. code-block:: python
162+
163+
from {{ joined_parts }} import {{ obj["short_name"] }}
164+
165+
{% if visible_properties %}
166+
167+
Property detail
168+
---------------
169+
{% for property in visible_properties %}
170+
{{ property.render() }}
171+
{% endfor %}
172+
{% endif %}
173+
174+
175+
{% if visible_attributes %}
176+
Attribute detail
177+
----------------
178+
{% for attribute in visible_attributes %}
179+
{{ attribute.render() }}
180+
{% endfor %}
181+
{% endif %}
182+
183+
{% if all_visible_methods %}
184+
Method detail
185+
-------------
186+
{% for method in all_visible_methods %}
187+
{{ method.render() }}
188+
{% endfor %}
189+
{% endif %}
190+
191+
{# ---------------------- End class details -------------------- #}

0 commit comments

Comments
 (0)