{#-
Shared Metadata Template

Provides consistent frontmatter generation across all documentation types.
Can be included or extended by other templates.
-#}

{#- Standard metadata that all docs should have -#}
{% macro standard_metadata(element, doc_type="doc", extra_metadata={}) %}
---
title: "{% if element and element.element_type == 'module' and not element.qualified_name|trim and autodoc_config is defined and 'python' in autodoc_config and 'display_name' in autodoc_config['python'] %}{{ autodoc_config['python']['display_name'] }}{% elif element and element.element_type == 'command-group' and element.qualified_name and '.' not in element.qualified_name and autodoc_config is defined and 'cli' in autodoc_config and 'display_name' in autodoc_config['cli'] %}{{ autodoc_config['cli']['display_name'] }}{% elif element and element.name and element.name|trim %}{{ element.name }}{% elif element and element.element_type == 'module' %}{%- set root_pkg_name = '' -%}{% if element.qualified_name and element.qualified_name|trim %}{%- set root_pkg_name = element.qualified_name.split('.')[0] -%}{% elif element.source_file %}{%- set root_pkg_name = element.source_file.parent.name -%}{% endif -%}{% if root_pkg_name %}{{ root_pkg_name }}{% elif doc_type in ['python-api', 'python-module', 'python-function', 'python-class'] %}API{% else %}Documentation{% endif %}{% elif doc_type in ['python-api', 'python-module', 'python-function', 'python-class'] %}API{% else %}Documentation{% endif %}"
type: "{{ doc_type }}"
{% if element and element.source_file %}
source_file: "{{ element.source_file | project_relative }}"
{% endif %}
{% if element and element.line_number %}
line_number: {{ element.line_number }}
{% endif %}
description: "{% if element.description %}{{ element.description | safe_description }}{% elif element and element.element_type == 'module' %}{%- set pkg_name = '' -%}{% if element.name and element.name|trim %}{%- set pkg_name = element.name -%}{% elif element.qualified_name and element.qualified_name|trim %}{%- set pkg_name = element.qualified_name.split('.')[0] -%}{% elif element.source_file %}{%- set pkg_name = element.source_file.parent.name -%}{% endif -%}{% if pkg_name %}{{ pkg_name }} package{% else %}{% if autodoc_config is defined and 'default_description' in autodoc_config %}{{ autodoc_config['default_description'] }}{% else %}Documentation{% endif %}{% endif %}{% elif autodoc_config is defined and 'default_description' in autodoc_config %}{{ autodoc_config['default_description'] }}{% else %}Documentation{% endif %}"
{% if element and element.element_type %}
element_type: "{{ element.element_type }}"
{% endif %}
{% if element and element.qualified_name %}
qualified_name: "{{ element.qualified_name }}"
{% endif %}

{#- Add any extra metadata passed in -#}
{% for key, value in extra_metadata.items() %}
{{ key }}: {{ value | tojson }}
{% endfor %}

{#- Auto-generated metadata -#}
generated_at: "{{ moment().isoformat() }}"
generator: "bengal-autodoc"
---
{% endmacro %}

{#- Python-specific metadata -#}
{% macro python_metadata(element, extra_metadata={}) %}
{{ standard_metadata(element, "python-api", {
    "module_path": element.qualified_name if element else "",
    "is_class": element.element_type == "class" if element else false,
    "is_function": element.element_type == "function" if element else false,
    "is_method": element.element_type == "method" if element else false
}) }}
{% endmacro %}

{#- CLI-specific metadata -#}
{% macro cli_metadata(element, extra_metadata={}) %}
{{ standard_metadata(element, "cli-reference", {
    "command_path": element.qualified_name if element else "",
    "is_command_group": element.element_type == "command-group" if element else false,
    "is_command": element.element_type == "command" if element else false
}) }}
{% endmacro %}

{#- OpenAPI-specific metadata -#}
{% macro openapi_metadata(element, extra_metadata={}) %}
{{ standard_metadata(element, "api-endpoint", {
    "endpoint_path": element.qualified_name if element else "",
    "http_method": element.metadata.method if element and element.metadata else "",
    "is_endpoint": element.element_type == "endpoint" if element else false,
    "is_schema": element.element_type == "schema" if element else false
}) }}
{% endmacro %}

{#- Utility function to get current timestamp -#}
{% macro moment() %}
{#- This would ideally use a proper datetime function, but for now use a placeholder -#}
{{ "2024-01-01T00:00:00Z" }}
{% endmacro %}
