{#-
Python API Documentation Base Template

Extends the main base template with Python-specific features and layout.
All Python documentation templates should extend this.
-#}

{% extends "base/base.md.jinja2" %}

{% from 'macros/parameter_table.md.jinja2' import python_parameters, returns_table, attribute_table %}
{% from 'macros/code_blocks.md.jinja2' import signature_block, code_examples %}
{% from 'macros/navigation.md.jinja2' import inheritance_chain %}

{% block doc_type %}python-api{% endblock %}

{% block badges %}
{% if element %}
{% if element.element_type == "class" %}
:::{badge} Class
:class: api-badge api-badge-class
:::
{% elif element.element_type == "function" %}
:::{badge} Function
:class: api-badge
:::
{% elif element.element_type == "method" %}
:::{badge} Method
:class: api-badge
:::
{% elif element.element_type == "module" %}
:::{badge} Module
:class: api-badge
:::
{% endif %}

{% if element.metadata and element.metadata.deprecated %}
:::{badge} Deprecated
:class: api-badge api-badge-deprecated
:::
{% endif %}

{% if element.metadata and element.metadata.is_async %}
:::{badge} Async
:class: api-badge api-badge-async
:::
{% endif %}
{% endif %}
{% endblock %}

{% block content %}
{#- Main description -#}
{%- call safe_section("description") -%}
{%- if element and element.description -%}
{{- element.description -}}
{%- else -%}
*No description provided.*
{%- endif -%}
{%- endcall -%}

{#- Deprecation warning -#}
{%- if element and element.metadata and element.metadata.deprecated -%}
{%- call safe_section("deprecation") -%}
:::{warning} Deprecated
{{- element.metadata.deprecated -}}
:::
{%- endcall -%}
{%- endif -%}

{#- Signature for functions/methods -#}
{%- if element and element.element_type in ["function", "method"] -%}
{%- call safe_section("signature") -%}
{%- if element.metadata and element.metadata.signature -%}
## Signature

{{- signature_block(element.metadata.signature) -}}
{%- endif -%}
{%- endcall -%}
{%- endif -%}

{#- Inheritance for classes -#}
{%- if element and element.element_type == "class" and element.metadata and element.metadata.bases -%}
{%- call safe_section("inheritance") -%}
## Inheritance

{{- inheritance_chain(element.metadata.bases) -}}
{%- endcall -%}
{%- endif -%}

{#- Parameters for functions/methods -#}
{%- if element and element.metadata and element.metadata.args -%}
{%- call safe_section("parameters") -%}
## Parameters

{{- python_parameters(element.metadata.args) -}}
{%- endcall -%}
{%- endif -%}

{#- Returns information -#}
{%- if element and element.metadata and element.metadata.returns -%}
{%- call safe_section("returns") -%}
## Returns

{{- returns_table(element.metadata.returns) -}}
{%- endcall -%}
{%- endif -%}

{#- Raises information -#}
{%- if element and element.metadata and element.metadata.raises -%}
{%- call safe_section("raises") -%}
## Raises

{%- for exc in element.metadata.raises -%}
- **`{{- exc.type -}}`**{%- if exc.description -%}: {{- exc.description -}}{%- endif -%}
{%- endfor -%}
{%- endcall -%}
{%- endif -%}

{#- Examples -#}
{%- if element and element.examples -%}
{%- call safe_section("examples") -%}
## Examples

{{- code_examples(element.examples) -}}
{%- endcall -%}
{%- endif -%}

{#- Child elements (methods, attributes, etc.) -#}
{% block child_elements %}
{#- Override in specific templates -#}
{% endblock %}
{% endblock %}
