244 lines
8.0 KiB
Python
244 lines
8.0 KiB
Python
"""Documentation templates."""
|
|
|
|
from typing import Optional
|
|
from pygments.formatters import HtmlFormatter
|
|
from pygments import highlight
|
|
from pygments.lexers import get_lexer_by_name
|
|
from pygments.styles import get_style_by_name
|
|
|
|
|
|
class DocumentationTemplate:
|
|
"""Template for documentation output."""
|
|
|
|
def __init__(self, style: str = "default", theme: str = "default"):
|
|
self.style = style
|
|
self.theme = theme
|
|
|
|
def format_function(
|
|
self,
|
|
name: str,
|
|
description: str,
|
|
parameters: list[tuple],
|
|
return_type: Optional[str],
|
|
return_description: Optional[str],
|
|
raises: list[tuple],
|
|
examples: list[str],
|
|
source_file: str,
|
|
line_number: int,
|
|
decorators: list[str],
|
|
) -> str:
|
|
"""Format function documentation."""
|
|
lines = [f"### {name}", ""]
|
|
|
|
if decorators:
|
|
for dec in decorators:
|
|
lines.append(f"```python\n{dec}\n```\n")
|
|
|
|
if description:
|
|
lines.append(f"{description}\n")
|
|
|
|
if parameters:
|
|
lines.append("**Parameters:**\n")
|
|
lines.append("| Name | Type | Default | Description |")
|
|
lines.append("|------|------|---------|-------------|")
|
|
for param in parameters:
|
|
if len(param) >= 4:
|
|
param_name, param_type, default, param_desc = param[:4]
|
|
else:
|
|
param_name = param[0] if len(param) > 0 else ""
|
|
param_type = param[1] if len(param) > 1 else None
|
|
default = param[2] if len(param) > 2 else None
|
|
param_desc = param[3] if len(param) > 3 else None
|
|
default_str = f"`{default}`" if default else "-"
|
|
desc_str = param_desc or "-"
|
|
type_str = f"`{param_type}`" if param_type else "-"
|
|
lines.append(f"| {param_name} | {type_str} | {default_str} | {desc_str} |")
|
|
lines.append("")
|
|
|
|
if return_type or return_description:
|
|
lines.append("**Returns:**\n")
|
|
if return_type:
|
|
lines.append(f"- Type: `{return_type}`")
|
|
if return_description:
|
|
lines.append(f"\n{return_description}")
|
|
lines.append("")
|
|
|
|
if raises:
|
|
lines.append("**Raises:**\n")
|
|
for exc_type, exc_desc in raises:
|
|
lines.append(f"- `{exc_type}`: {exc_desc}")
|
|
lines.append("")
|
|
|
|
if examples:
|
|
lines.append("**Examples:**\n")
|
|
for example in examples:
|
|
lines.append(f"```python\n{example}\n```\n")
|
|
|
|
lines.append(f"*Source: {source_file}:{line_number}*")
|
|
|
|
return "\n".join(lines)
|
|
|
|
def format_class(
|
|
self,
|
|
name: str,
|
|
description: str,
|
|
attributes: list[tuple],
|
|
methods: list[str],
|
|
parameters: list[tuple],
|
|
decorators: list[str],
|
|
source_file: str,
|
|
line_number: int,
|
|
) -> str:
|
|
"""Format class documentation."""
|
|
lines = [f"## {name}", ""]
|
|
|
|
if decorators:
|
|
for dec in decorators:
|
|
lines.append(f"```python\n{dec}\n```\n")
|
|
|
|
if description:
|
|
lines.append(f"{description}\n")
|
|
|
|
if parameters:
|
|
lines.append("**Inherits:**\n")
|
|
for param in parameters:
|
|
if isinstance(param, tuple) and len(param) >= 2:
|
|
base_name, base_desc = param[0], param[1]
|
|
else:
|
|
base_name, base_desc = str(param), ""
|
|
lines.append(f"- {base_name}: {base_desc or ''}")
|
|
lines.append("")
|
|
|
|
if attributes:
|
|
lines.append("**Attributes:**\n")
|
|
lines.append("| Name | Type | Description |")
|
|
lines.append("|------|------|-------------|")
|
|
for attr in attributes:
|
|
if len(attr) >= 3:
|
|
attr_name, attr_type, attr_desc = attr[:3]
|
|
else:
|
|
attr_name = attr[0] if len(attr) > 0 else ""
|
|
attr_type = attr[1] if len(attr) > 1 else None
|
|
attr_desc = attr[2] if len(attr) > 2 else None
|
|
type_str = f"`{attr_type}`" if attr_type else "-"
|
|
desc_str = attr_desc or "-"
|
|
lines.append(f"| {attr_name} | {type_str} | {desc_str} |")
|
|
lines.append("")
|
|
|
|
if methods:
|
|
lines.append("**Methods:**\n")
|
|
for method in methods:
|
|
lines.append(f"- {method}")
|
|
lines.append("")
|
|
|
|
lines.append(f"*Source: {source_file}:{line_number}*")
|
|
|
|
return "\n".join(lines)
|
|
|
|
def format_module(
|
|
self,
|
|
name: str,
|
|
description: str,
|
|
imports: list[str],
|
|
elements_count: dict,
|
|
) -> str:
|
|
"""Format module documentation."""
|
|
lines = [f"# {name}", ""]
|
|
|
|
if description:
|
|
lines.append(f"{description}\n")
|
|
|
|
lines.append("## Summary")
|
|
if elements_count:
|
|
summary_parts = []
|
|
if elements_count.get("functions"):
|
|
summary_parts.append(f"{elements_count['functions']} functions")
|
|
if elements_count.get("classes"):
|
|
summary_parts.append(f"{elements_count['classes']} classes")
|
|
if elements_count.get("constants"):
|
|
summary_parts.append(f"{elements_count['constants']} constants")
|
|
if summary_parts:
|
|
lines.append(f"This module contains {', '.join(summary_parts)}.")
|
|
lines.append("")
|
|
|
|
if imports:
|
|
lines.append("## Imports")
|
|
for imp in imports[:10]:
|
|
lines.append(f"- `{imp}`")
|
|
if len(imports) > 10:
|
|
lines.append(f"- ... and {len(imports) - 10} more")
|
|
lines.append("")
|
|
|
|
return "\n".join(lines)
|
|
|
|
def format_interface(
|
|
self,
|
|
name: str,
|
|
description: str,
|
|
properties: list[tuple],
|
|
) -> str:
|
|
"""Format interface documentation."""
|
|
lines = [f"## {name}", ""]
|
|
|
|
if description:
|
|
lines.append(f"{description}\n")
|
|
|
|
if properties:
|
|
lines.append("**Properties:**\n")
|
|
lines.append("| Name | Type | Description |")
|
|
lines.append("|------|------|-------------|")
|
|
for prop in properties:
|
|
if len(prop) >= 3:
|
|
prop_name, prop_type, prop_desc = prop[:3]
|
|
else:
|
|
prop_name = prop[0] if len(prop) > 0 else ""
|
|
prop_type = prop[1] if len(prop) > 1 else None
|
|
prop_desc = prop[2] if len(prop) > 2 else None
|
|
type_str = f"`{prop_type}`" if prop_type else "-"
|
|
desc_str = prop_desc or "-"
|
|
lines.append(f"| {prop_name} | {type_str} | {desc_str} |")
|
|
lines.append("")
|
|
|
|
return "\n".join(lines)
|
|
|
|
|
|
class SyntaxHighlighter:
|
|
"""Syntax highlighting utilities."""
|
|
|
|
THEMES = {
|
|
"default": "default",
|
|
"dark": "monokai",
|
|
"light": "manni",
|
|
"colorful": "rainbow_dash",
|
|
}
|
|
|
|
def __init__(self, theme: str = "default"):
|
|
self.theme = self.THEMES.get(theme, "default")
|
|
self.style = get_style_by_name(self.theme)
|
|
self.formatter = HtmlFormatter(
|
|
style=self.style,
|
|
linenos=True,
|
|
cssclass="code-highlight",
|
|
noclasses=False,
|
|
)
|
|
|
|
def highlight(self, code: str, language: str) -> str:
|
|
"""Highlight code with syntax highlighting.
|
|
|
|
Args:
|
|
code: Code to highlight
|
|
language: Programming language
|
|
|
|
Returns:
|
|
HTML formatted highlighted code
|
|
"""
|
|
try:
|
|
lexer = get_lexer_by_name(language)
|
|
return highlight(code, lexer, self.formatter)
|
|
except Exception:
|
|
return f"<pre><code>{code}</code></pre>"
|
|
|
|
def get_css(self) -> str:
|
|
"""Get CSS for syntax highlighting."""
|
|
return self.formatter.get_style_defs()
|