diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index db14d9907..fec894586 100644 --- a/.pre-commit-config.yaml +++ b/.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/' diff --git a/src/ansys_sphinx_theme/__init__.py b/src/ansys_sphinx_theme/__init__.py index 1c6e87c0b..af996385b 100644 --- a/src/ansys_sphinx_theme/__init__.py +++ b/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": diff --git a/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/autoapi/index.rst b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/autoapi/index.rst new file mode 100644 index 000000000..d45f7b6bc --- /dev/null +++ b/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 %} diff --git a/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/autoapi/python/class.rst b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/autoapi/python/class.rst new file mode 100644 index 000000000..1613245b6 --- /dev/null +++ b/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 -------------------- #} diff --git a/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/autoapi/python/module.rst b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/autoapi/python/module.rst new file mode 100644 index 000000000..9d7bdb983 --- /dev/null +++ b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/autoapi/python/module.rst @@ -0,0 +1,236 @@ +{# ------------------------- 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 %} + +{% macro toctree_from_objects_list(objects_list, icon="", needs_index="false") -%} + +.. toctree:: + :titlesonly: + :maxdepth: 1 + :hidden: + +{% for obj in objects_list %} + {% if needs_index == "true" %} + {{ icon }} {{ obj.short_name }}<{{ obj.short_name }}/index.rst> + {% else %} + {{ icon }} {{ obj.short_name }}<{{ obj.short_name }}> + {% endif %} +{% endfor %} +{%- endmacro %} + +{# --------------------------- End macros definition ----------------------- #} + +{% if not obj.display %} +:orphan: +{% endif %} + +{% if obj.name.split(".") | length == 3 %} +The ``{{ obj.name }}`` library +{{ "================" + "=" * obj.name|length }} +{% else %} +{% if obj.type == "package" %} +The ``{{ obj.short_name }}`` package +{{ "====================" + "=" * obj.short_name|length }} +{% else %} +The ``{{ obj.short_name }}.py`` module +{{ "==================" + "=" * obj.short_name|length }} +{% endif %} +{% endif %} + +.. py:module:: {{ obj.name }} + +{# ---------------------- Begin module summary -------------------- #} + +Summary +------- + +{% if obj.all is not none %} +{% set visible_children = obj.children|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 %} + +{% set visible_subpackages = obj.subpackages|selectattr("display")|list %} +{% set visible_submodules = obj.submodules|selectattr("display")|list %} + +{% set visible_classes_and_interfaces = visible_children|selectattr("type", "equalto", "class")|list %} +{% set visible_functions = visible_children|selectattr("type", "equalto", "function")|list %} +{% set visible_attributes_and_constants = visible_children|selectattr("type", "equalto", "data")|list %} +{% set visible_exceptions = visible_children|selectattr("type", "equalto", "exception")|list %} + +{% set visible_classes = [] %} +{% set visible_interfaces = [] %} +{% set visible_enums = [] %} +{% for element in visible_classes_and_interfaces %} + {% if element.name.startswith("I") and element.name[1].isupper() and ("enum.Enum" not in element.bases) %} + {% set _ = visible_interfaces.append(element) %} + {% elif "enum.Enum" in element.bases %} + {% set _ = visible_enums.append(element) %} + {% else %} + {% set _ = visible_classes.append(element) %} + {% endif %} +{% endfor %} + +{% set visible_attributes = [] %} +{% set visible_constants = [] %} +{% for element in visible_attributes_and_constants %} + {% if element.name.isupper() %} + {% set _ = visible_constants.append(element) %} + {% else %} + {% set _ = visible_attributes.append(element) %} + {% endif %} +{% endfor %} + +{% set module_objects = visible_subpackages + visible_submodules + visible_classes + visible_interfaces + visible_enums + visible_exceptions + visible_functions + visible_constants + visible_attributes %} + +{# ---------------------- End module summary -------------------- #} +{# ---------------------- Begin module tabset -------------------- #} +{% if module_objects %} + +.. py:currentmodule:: {{ obj.short_name }} +.. tab-set:: + +{% if visible_subpackages %} + {{ tab_item_from_objects_list(visible_subpackages, "Subpackages") }} +{% endif %} + +{% if visible_submodules %} + {{ tab_item_from_objects_list(visible_submodules, "Submodules") }} +{% endif %} + +{% if visible_interfaces %} + {{ tab_item_from_objects_list(visible_interfaces, "Interfaces") }} +{% endif %} + +{% if visible_classes %} + {{ tab_item_from_objects_list(visible_classes, "Classes") }} +{% endif %} + +{% if visible_enums %} + {{ tab_item_from_objects_list(visible_enums, "Enums") }} +{% endif %} + +{% if visible_exceptions %} + {{ tab_item_from_objects_list(visible_exceptions, "Exceptions") }} +{% endif %} + +{% if visible_functions %} + {{ tab_item_from_objects_list(visible_functions, "Functions") }} +{% endif %} + +{% if visible_attributes %} + {{ tab_item_from_objects_list(visible_attributes, "Attributes") }} +{% endif %} + +{% if visible_constants %} + {{ tab_item_from_objects_list(visible_constants, "Constants") }} +{% endif %} +{% endif %} + +{# ---------------------- End module tabset -------------------- #} +{# ------------------------ Begin toctree definition ----------------------- #} + +{% block subpackages %} +{% if visible_subpackages %} +{{ toctree_from_objects_list(visible_subpackages, "🖿", needs_index="true") }} +{% endif %} +{% endblock %} + +{% block submodules %} +{% if visible_submodules %} +{{ toctree_from_objects_list(visible_submodules, "🗎", needs_index="true") }} +{% endif %} +{% endblock %} + +{% block class %} +{% if render_in_single_page and "class" in render_in_single_page %} +{% if visible_interfaces %} +{{ toctree_from_objects_list(visible_interfaces, "🝆") }} +{% endif %} + +{% if visible_classes %} +{{ toctree_from_objects_list(visible_classes, "🝆") }} +{% endif %} + +{% if visible_enums %} +{{ toctree_from_objects_list(visible_enums, "≔") }} +{% endif %} + +{% if visible_exceptions %} +{{ toctree_from_objects_list(visible_exceptions, "") }} +{% endif %} +{% endif %} +{% endblock %} + +{% block functions %} +{% if render_in_single_page and visible_functions and "function" in render_in_single_page %} +{{ toctree_from_objects_list(visible_functions, "𝑓(x)") }} +{% endif %} +{% endblock %} + +{% block constants %} +{% if render_in_single_page and visible_constants and "constant" in render_in_single_page %} +{{ toctree_from_objects_list(visible_constants, "π") }} +{% endif %} +{% endblock %} + +{# ------------------------- End toctree definition ------------------------ #} + + +{# ------------------------ Begin module description ----------------------- #} + +{% if obj.docstring %} +Description +----------- + +{{ obj.docstring }} +{% endif %} + +{# ------------------------- End module description ------------------------ #} + + +{# -------------------------- Begin module detail -------------------------- #} + +{% set module_objects_in_this_page = visible_classes + visible_interfaces + visible_enums + visible_exceptions + visible_functions + visible_constants + visible_attributes %} +{% if module_objects_in_this_page %} +{% set visible_objects_in_this_page = [] %} + +{% if render_in_single_page %} +{% for obj in module_objects_in_this_page %} +{% if obj.type not in render_in_single_page %} +{% set _ = visible_objects_in_this_page.append(obj) %} +{% endif %} +{% endfor %} +{% else %} +{% set visible_objects_in_this_page = module_objects_in_this_page %} +{% endif %} + +{% if visible_objects_in_this_page %} +Module detail +------------- + +{% for obj in visible_objects_in_this_page %} +{{ obj.render() }} +{% endfor %} + +{% endif %} +{% endif %} + +{# ---------------------- End module detail description -------------------- #} diff --git a/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/autoapi/python/property.rst b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/autoapi/python/property.rst new file mode 100644 index 000000000..a142c81a7 --- /dev/null +++ b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/autoapi/python/property.rst @@ -0,0 +1,23 @@ +{%- if obj.display %} +.. py:property:: {{ obj.short_name }} + :canonical: {{ obj["obj"]["full_name"] }} + {% set module_path = obj.obj["full_name"].split('.') %} + {% set module_name = '.'.join(module_path[:2]) %} + {% if obj.annotation and module_name in obj.annotation and "[" not in obj.annotation %} + {% set split_parts = obj.annotation.split('.') %} + {% set last_part = split_parts[-1] %} + :type: {{ last_part }} + {% else %} + :type: {{ obj.annotation }} + {% endif %} + + {% if obj.properties %} + {% for property in obj.properties %} + :{{ property }}: + {% endfor %} + {% endif %} + + {% if obj.docstring %} + {{ obj.docstring|indent(3) }} + {% endif %} +{% endif %}