{#- Macro: Render parameters as table or list based on count -#}
{% macro render_parameters(args) -%}
{% set param_count = args | length -%}

:::{rubric} Parameters
:class: rubric-parameters
:::

::::{dropdown} {{ param_count }} parameters (click to expand)
:open: false

:::{list-table}
:header-rows: 1
:widths: 20 20 20 40

* - Name
  - Type
  - Default
  - Description
{% for arg in args -%}
* - `{{ arg.name }}`
  - {% if arg.annotation %}`{{ arg.annotation }}`{% else %}-{% endif %}

  - {% if arg.default %}`{{ arg.default }}`{% else %}-{% endif %}

  - {% if arg.docstring %}{{ arg.docstring }}{% else %}-{% endif %}

{% endfor -%}
:::

::::

{%- endmacro %}

{#- Macro: Render attributes as table within dropdown -#}
{% macro render_attributes(attrs) -%}
{% set attr_count = attrs | length -%}

:::{rubric} Attributes
:class: rubric-attributes
:::

::::{dropdown} {{ attr_count }} attributes (click to expand)
:open: false

:::{list-table}
:header-rows: 1
:widths: 25 25 50

* - Name
  - Type
  - Description
{% for attr in attrs -%}
* - `{{ attr.name }}`
  - {% if attr.metadata.annotation %}`{{ attr.metadata.annotation }}`{% else %}-{% endif %}

  - {% if attr.description %}{{ attr.description }}{% else %}-{% endif %}

{% endfor -%}
:::

::::

{%- endmacro %}

{#- Macro: Render examples with proper code block wrapping -#}
{% macro render_examples(examples) %}
{% if examples %}

:::{rubric} Examples
:class: rubric-examples
:::
{% for example in examples %}
{% if not example.strip().startswith('```') %}
```python
{{ example.strip() }}
```
{% else %}
{{ example }}
{% endif %}

{% endfor %}
{% endif %}
{% endmacro %}

{#- Macro: Render raises section -#}
{% macro render_raises(raises) %}
{% if raises %}

:::{rubric} Raises
:class: rubric-raises
:::
{% for exc in raises %}
- **`{{ exc.type }}`**{%- if exc.description %}: {{ exc.description }}{%- endif %}
{% endfor %}
{% endif %}
{% endmacro %}

{#- Macro: Render notes as admonitions -#}
{% macro render_notes(notes) %}
{% if notes %}

{% for note in notes %}
```{note}
{{ note }}
```

{% endfor %}
{% endif %}
{% endmacro %}

{#- Macro: Render warnings as admonitions -#}
{% macro render_warnings(warnings) %}
{% if warnings %}

{% for warning in warnings %}
```{warning}
{{ warning }}
```

{% endfor %}
{% endif %}
{% endmacro %}

---
title: "{{ element.name }}"
type: python-module
source_file: "{{ element.source_file | project_relative }}"
css_class: api-content
description: "{% if element.description %}{% set lines = element.description.split('\n') %}{% set desc_lines = [] %}{% for line in lines %}{% if not line.strip().startswith('#') %}{% set _ = desc_lines.append(line) %}{% endif %}{% endfor %}{{ desc_lines | join(' ') | truncate(200, True, '...') }}{% else %}Python module documentation{% endif %}"
---

# {{ element.name }}

{% if element.description %}
{{ element.description }}
{% else %}
*No module description provided.*
{% endif %}

---

{% if element.children | selectattr('element_type', 'equalto', 'class') | list %}
## Classes

{% for cls in element.children | selectattr('element_type', 'equalto', 'class') %}
### `{{ cls.name }}`

{% if cls.metadata.bases %}
**Inherits from:** {% for base in cls.metadata.bases %}`{{ base }}`{% if not loop.last %}, {% endif %}{% endfor %}
{% endif %}

{% if cls.description %}
{{ cls.description }}
{% else %}
*No class description provided.*
{% endif %}

{% if cls.metadata.is_dataclass %}
```{info}
This is a dataclass.
```
{% endif %}

{% if cls.children | selectattr('element_type', 'equalto', 'attribute') | list %}
{{ render_attributes(cls.children | selectattr('element_type', 'equalto', 'attribute') | list) }}
{% endif %}

{% if cls.children | selectattr('metadata.is_property', 'equalto', true) | list %}
:::{rubric} Properties
:class: rubric-properties
:::
{% for prop in cls.children | selectattr('metadata.is_property', 'equalto', true) %}
#### `{{ prop.name }}` @property

```python
@property
{{ prop.metadata.signature }}
```

{% if prop.description %}
{{ prop.description }}
{% endif %}
{% endfor %}
{% endif %}

{% if cls.children | selectattr('element_type', 'equalto', 'method') | list %}
:::{rubric} Methods
:class: rubric-methods
:::
{% for method in cls.children | selectattr('element_type', 'equalto', 'method') %}
{% if not method.name.startswith('_') or method.name.startswith('__') %}
#### `{{ method.name }}`{% if method.metadata.is_async %} @async{% endif %}{% if method.metadata.is_classmethod %} @classmethod{% endif %}{% if method.metadata.is_staticmethod %} @staticmethod{% endif %}

```python
{{ method.metadata.signature }}
```

{% if method.description %}
{{ method.description }}
{% else %}
*No description provided.*
{% endif %}

{% if method.metadata.parsed_doc.deprecated %}
```{warning} Deprecated
{{ method.metadata.parsed_doc.deprecated }}
```

{% endif %}

{% if method.metadata.is_async %}
```{info} Async Method
This is an asynchronous method. Use `await` when calling.
```

{% endif %}

{% if method.metadata.args %}
{{ render_parameters(method.metadata.args) }}
{% endif %}
{% if method.metadata.returns %}

:::{rubric} Returns
:class: rubric-returns
:::

`{{ method.metadata.returns }}`{%- if method.metadata.parsed_doc.returns %} - {{ method.metadata.parsed_doc.returns }}{%- endif %}

{% endif %}
{{ render_raises(method.metadata.parsed_doc.raises) }}
{{ render_notes(method.metadata.parsed_doc.notes) }}
{{ render_warnings(method.metadata.parsed_doc.warnings) }}
{{ render_examples(method.metadata.parsed_doc.examples) }}
{% if method.metadata.parsed_doc.see_also %}
**See Also:** {% for ref in method.metadata.parsed_doc.see_also %}{{ ref }}{% if not loop.last %}, {% endif %}{% endfor %}

{% endif %}
---
{% endif %}
{% endfor %}
{% endif %}

{% endfor %}
{% endif %}

{% if element.children | selectattr('element_type', 'equalto', 'function') | list %}
## Functions

{% for func in element.children | selectattr('element_type', 'equalto', 'function') %}
{% if not func.name.startswith('_') %}
### `{{ func.name }}`{% if func.metadata.is_async %} @async{% endif %}

```python
{{ func.metadata.signature }}
```

{% if func.description %}
{{ func.description }}
{% else %}
*No description provided.*
{% endif %}

{% if func.metadata.parsed_doc.deprecated %}
```{warning} Deprecated
{{ func.metadata.parsed_doc.deprecated }}
```

{% endif %}

{% if func.metadata.is_async %}
```{info} Async Function
This is an asynchronous function. Use `await` when calling.
```

{% endif %}

{% if func.metadata.args %}
{{ render_parameters(func.metadata.args) }}
{% endif %}
{% if func.metadata.returns %}
:::{rubric} Returns
:class: rubric-returns
:::
`{{ func.metadata.returns }}`{%- if func.metadata.parsed_doc.returns %} - {{ func.metadata.parsed_doc.returns }}{%- endif %}

{% endif %}
{{ render_raises(func.metadata.parsed_doc.raises) }}
{{ render_notes(func.metadata.parsed_doc.notes) }}
{{ render_warnings(func.metadata.parsed_doc.warnings) }}
{{ render_examples(func.metadata.parsed_doc.examples) }}
{% if func.metadata.parsed_doc.see_also %}
**See Also:** {% for ref in func.metadata.parsed_doc.see_also %}{{ ref }}{% if not loop.last %}, {% endif %}{% endfor %}

{% endif %}
---
{% endif %}
{% endfor %}
{% endif %}
