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]>

.pre-commit-config.yaml

@@ -50,3 +50,4 @@ repos:
   hooks:
   - id: blacken-docs
     additional_dependencies: [black==23.7.0]
+    exclude: 'src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/'

src/ansys_sphinx_theme/__init__.py

@@ -1,5 +1,6 @@
 """This is the ansys-sphinx-theme module."""
 import logging
+import os
 import pathlib
 from typing import Any, Dict
 
@@ -21,6 +22,7 @@
 JS_PATH = STATIC_PATH / "js"
 CSS_PATH = STYLE_PATH / "ansys_sphinx_theme.css"
 TEMPLATES_PATH = THEME_PATH / "_templates"
+AUTOAPI_TEMPLATES_PATH = TEMPLATES_PATH / "autoapi"
 JS_FILE = JS_PATH / "table.js"
 
 # make logo paths available
@@ -66,6 +68,25 @@ def get_version_match(semver: str) -> str:
     return ".".join([major, minor])
 
 
+def get_autoapi_templates_dir_relative_path(path: pathlib.Path) -> str:
+    """Return a string representing the relative path for autoapi templates.
+
+    Parameters
+    ----------
+    path : pathlib.Path
+        Path to the desired file.
+
+    Returns
+    -------
+    str
+        A string rerpesenting the relative path to the autoapi templates.
+
+    """
+    return os.path.relpath(
+        str(AUTOAPI_TEMPLATES_PATH.absolute()), start=str(path.parent.absolute())
+    )
+
+
 def convert_version_to_pymeilisearch(semver: str) -> str:
     """Convert a semantic version number to pymeilisearch-compatible format.
 
@@ -187,7 +208,7 @@ def fix_edit_link_page(link: str) -> str:
                     logging.debug(f"An error occurred: {e}")  # Log the exception as debug info
                     return link
 
-        elif "autoapi" in pagename:
+        elif pagename in ["autoapi", "api"]:
             for obj_node in list(doctree.findall(addnodes.desc)):
                 domain = obj_node.get("domain")
                 if domain != "py":

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

@@ -0,0 +1,15 @@
+API reference
+=============
+
+This section describes {{ project_name }} endpoints, their capabilities, and how
+to interact with them programmatically.
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 3
+
+   {% for page in pages %}
+   {% if (page.top_level_object or page.name.split('.') | length == 3) and page.display %}
+   🖿 {{ page.name }}<{{ page.include_path }}>
+   {% endif %}
+   {% endfor %}

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

@@ -0,0 +1,191 @@
+{# ------------------------- Begin macros definition ----------------------- #}
+
+{% macro tab_item_from_objects_list(objects_list, title="") -%}
+
+    .. tab-item:: {{ title }}
+
+        .. list-table::
+          :header-rows: 0
+          :widths: auto
+
+          {% for obj in objects_list %}
+          * - :py:attr:`~{{ obj.name }}`
+            - {{ obj.summary }}
+          {% endfor %}
+{%- endmacro %}
+
+{# --------------------------- End macros definition ----------------------- #}
+
+{% if obj.display %}
+
+{% if render_in_single_page and obj["type"] in render_in_single_page %}
+{{ obj.short_name }}
+{{"=" * obj.name|length }}
+{% endif %}
+
+.. py:{{ obj["type"] }}:: {{ obj["short_name"] }}{% if obj["args"] %}({{ obj["args"] }}){% endif %}
+
+{% if render_in_single_page and obj["type"] in render_in_single_page %}
+   :canonical: {{ obj["obj"]["full_name"] }}
+{% 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.summary|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_properties = obj.properties|selectattr("display")|list %}
+{% else %}
+{% set visible_properties = obj.properties|rejectattr("inherited")|selectattr("display")|list %}
+{% endif %}
+
+{% 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 all_visible_methods = obj.methods|selectattr("display")|list %}
+{% else %}
+{% set all_visible_methods = obj.methods|rejectattr("inherited")|selectattr("display")|list %}
+{% endif %}
+
+{% set visible_abstract_methods = [] %}
+{% set visible_constructor_methods = [] %}
+{% set visible_instance_methods = [] %}
+{% set visible_special_methods = [] %}
+{% set visible_static_methods = [] %}
+
+{% for element in all_visible_methods %}
+    {% if "abstractmethod" in element.properties %}
+        {% set _ = visible_abstract_methods.append(element) %}
+
+    {% elif "staticmethod" in element.properties %}
+        {% set _ = visible_static_methods.append(element) %}
+
+    {% elif "classmethod" in element.properties or element.name in ["__new__", "__init__"] %}
+        {% set _ = visible_constructor_methods.append(element) %}
+
+    {% elif element.name.startswith("__") and element.name.endswith("__") and element.name not in ["__new__", "__init__"] %}
+        {% set _ = visible_special_methods.append(element) %}
+
+    {% else %}
+        {% set _ = visible_instance_methods.append(element) %}
+
+    {% endif %}
+{% endfor %}
+
+
+{% set class_objects = visible_properties + visible_attributes + all_visible_methods %}
+
+{# ------------------------ Begin tabset definition ----------------------- #}
+
+{% if class_objects %}
+
+{% if render_in_single_page and obj["type"] in render_in_single_page %}
+Overview
+--------
+.. py:currentmodule:: {{ obj.short_name }}
+{% endif %}
+.. tab-set::
+
+{% if visible_abstract_methods %}
+    {{ tab_item_from_objects_list(visible_abstract_methods, "Abstract methods") }}
+{% endif %}
+
+{% if visible_constructor_methods %}
+    {{ tab_item_from_objects_list(visible_constructor_methods, "Constructors") }}
+{% endif %}
+
+{% if visible_instance_methods %}
+    {{ tab_item_from_objects_list(visible_instance_methods, "Methods") }}
+{% endif %}
+
+{% if visible_properties %}
+    {{ tab_item_from_objects_list(visible_properties, "Properties") }}
+{% endif %}
+
+{% if visible_attributes %}
+    {{ tab_item_from_objects_list(visible_attributes, "Attributes") }}      
+{% endif %}
+
+{% if visible_static_methods %}
+    {{ tab_item_from_objects_list(visible_static_methods, "Static methods") }}
+{% endif %}
+
+{% if visible_special_methods %}
+    {{ tab_item_from_objects_list(visible_special_methods, "Special methods") }}
+{% endif %}
+
+{% endif %}
+{% endif %}
+{# ---------------------- End class tabset -------------------- #}
+{# ---------------------- Begin class datails -------------------- #}
+
+Import detail
+-------------
+{% set split_parts = obj.obj["full_name"].split('.') %}
+{% set joined_parts = '.'.join(split_parts[:-1]) %}
+
+.. code-block:: python
+
+    from {{ joined_parts }} import {{ obj["short_name"] }}
+
+{% if visible_properties  %}
+
+Property detail
+---------------
+{% for property in visible_properties %}
+{{ property.render() }}
+{% endfor %}
+{% endif %}
+
+
+{% if visible_attributes  %}
+Attribute detail
+----------------
+{% for attribute in visible_attributes %}
+{{ attribute.render() }}
+{% endfor %}
+{% endif %}
+
+{% if all_visible_methods  %}
+Method detail
+-------------
+{% for method in all_visible_methods %}
+{{ method.render() }}
+{% endfor %}
+{% endif %}
+
+{# ---------------------- End class details -------------------- #}