, \
- MCRF_PROPERTY(opacity, \
- "Opacity level (0.0 = transparent, 1.0 = opaque). " \
- "Automatically clamped to valid range [0.0, 1.0]." \
- ), NULL}
+ "Opacity (0.0 = transparent, 1.0 = opaque)", NULL}
// UIEntity specializations are defined in UIEntity.cpp after UIEntity class is complete
diff --git a/src/UICaption.cpp b/src/UICaption.cpp
index 33cff43..6ac1adb 100644
--- a/src/UICaption.cpp
+++ b/src/UICaption.cpp
@@ -273,16 +273,8 @@ PyGetSetDef UICaption::getsetters[] = {
//{"children", (getter)PyUIFrame_get_children, NULL, "UICollection of objects on top of this one", NULL},
{"text", (getter)UICaption::get_text, (setter)UICaption::set_text, "The text displayed", NULL},
{"font_size", (getter)UICaption::get_float_member, (setter)UICaption::set_float_member, "Font size (integer) in points", (void*)5},
- {"click", (getter)UIDrawable::get_click, (setter)UIDrawable::set_click,
- MCRF_PROPERTY(click,
- "Callable executed when object is clicked. "
- "Function receives (x, y) coordinates of click."
- ), (void*)PyObjectsEnum::UICAPTION},
- {"z_index", (getter)UIDrawable::get_int, (setter)UIDrawable::set_int,
- MCRF_PROPERTY(z_index,
- "Z-order for rendering (lower values rendered first). "
- "Automatically triggers scene resort when changed."
- ), (void*)PyObjectsEnum::UICAPTION},
+ {"click", (getter)UIDrawable::get_click, (setter)UIDrawable::set_click, "Object called with (x, y, button) when clicked", (void*)PyObjectsEnum::UICAPTION},
+ {"z_index", (getter)UIDrawable::get_int, (setter)UIDrawable::set_int, "Z-order for rendering (lower values rendered first)", (void*)PyObjectsEnum::UICAPTION},
{"name", (getter)UIDrawable::get_name, (setter)UIDrawable::set_name, "Name for finding elements", (void*)PyObjectsEnum::UICAPTION},
UIDRAWABLE_GETSETTERS,
{NULL}
diff --git a/src/UIFrame.cpp b/src/UIFrame.cpp
index 8eb0522..4ceb8b8 100644
--- a/src/UIFrame.cpp
+++ b/src/UIFrame.cpp
@@ -398,16 +398,8 @@ PyGetSetDef UIFrame::getsetters[] = {
{"fill_color", (getter)UIFrame::get_color_member, (setter)UIFrame::set_color_member, "Fill color of the rectangle", (void*)0},
{"outline_color", (getter)UIFrame::get_color_member, (setter)UIFrame::set_color_member, "Outline color of the rectangle", (void*)1},
{"children", (getter)UIFrame::get_children, NULL, "UICollection of objects on top of this one", NULL},
- {"click", (getter)UIDrawable::get_click, (setter)UIDrawable::set_click,
- MCRF_PROPERTY(click,
- "Callable executed when object is clicked. "
- "Function receives (x, y) coordinates of click."
- ), (void*)PyObjectsEnum::UIFRAME},
- {"z_index", (getter)UIDrawable::get_int, (setter)UIDrawable::set_int,
- MCRF_PROPERTY(z_index,
- "Z-order for rendering (lower values rendered first). "
- "Automatically triggers scene resort when changed."
- ), (void*)PyObjectsEnum::UIFRAME},
+ {"click", (getter)UIDrawable::get_click, (setter)UIDrawable::set_click, "Object called with (x, y, button) when clicked", (void*)PyObjectsEnum::UIFRAME},
+ {"z_index", (getter)UIDrawable::get_int, (setter)UIDrawable::set_int, "Z-order for rendering (lower values rendered first)", (void*)PyObjectsEnum::UIFRAME},
{"name", (getter)UIDrawable::get_name, (setter)UIDrawable::set_name, "Name for finding elements", (void*)PyObjectsEnum::UIFRAME},
{"pos", (getter)UIDrawable::get_pos, (setter)UIDrawable::set_pos, "Position as a Vector", (void*)PyObjectsEnum::UIFRAME},
{"clip_children", (getter)UIFrame::get_clip_children, (setter)UIFrame::set_clip_children, "Whether to clip children to frame bounds", NULL},
diff --git a/src/UIGrid.cpp b/src/UIGrid.cpp
index 060c9c0..b07e596 100644
--- a/src/UIGrid.cpp
+++ b/src/UIGrid.cpp
@@ -1418,11 +1418,7 @@ PyGetSetDef UIGrid::getsetters[] = {
{"center_y", (getter)UIGrid::get_float_member, (setter)UIGrid::set_float_member, "center of the view Y-coordinate", (void*)5},
{"zoom", (getter)UIGrid::get_float_member, (setter)UIGrid::set_float_member, "zoom factor for displaying the Grid", (void*)6},
- {"click", (getter)UIDrawable::get_click, (setter)UIDrawable::set_click,
- MCRF_PROPERTY(click,
- "Callable executed when object is clicked. "
- "Function receives (x, y) coordinates of click."
- ), (void*)PyObjectsEnum::UIGRID},
+ {"click", (getter)UIDrawable::get_click, (setter)UIDrawable::set_click, "Object called with (x, y, button) when clicked", (void*)PyObjectsEnum::UIGRID},
{"texture", (getter)UIGrid::get_texture, NULL, "Texture of the grid", NULL}, //TODO 7DRL-day2-item5
{"fill_color", (getter)UIGrid::get_fill_color, (setter)UIGrid::set_fill_color, "Background fill color of the grid", NULL},
@@ -1432,11 +1428,7 @@ PyGetSetDef UIGrid::getsetters[] = {
{"perspective_enabled", (getter)UIGrid::get_perspective_enabled, (setter)UIGrid::set_perspective_enabled,
"Whether to use perspective-based FOV rendering. When True with no valid entity, "
"all cells appear undiscovered.", NULL},
- {"z_index", (getter)UIDrawable::get_int, (setter)UIDrawable::set_int,
- MCRF_PROPERTY(z_index,
- "Z-order for rendering (lower values rendered first). "
- "Automatically triggers scene resort when changed."
- ), (void*)PyObjectsEnum::UIGRID},
+ {"z_index", (getter)UIDrawable::get_int, (setter)UIDrawable::set_int, "Z-order for rendering (lower values rendered first)", (void*)PyObjectsEnum::UIGRID},
{"name", (getter)UIDrawable::get_name, (setter)UIDrawable::set_name, "Name for finding elements", (void*)PyObjectsEnum::UIGRID},
UIDRAWABLE_GETSETTERS,
{NULL} /* Sentinel */
diff --git a/src/UISprite.cpp b/src/UISprite.cpp
index a1d697b..4be581c 100644
--- a/src/UISprite.cpp
+++ b/src/UISprite.cpp
@@ -339,16 +339,8 @@ PyGetSetDef UISprite::getsetters[] = {
{"sprite_index", (getter)UISprite::get_int_member, (setter)UISprite::set_int_member, "Which sprite on the texture is shown", NULL},
{"sprite_number", (getter)UISprite::get_int_member, (setter)UISprite::set_int_member, "Sprite index (DEPRECATED: use sprite_index instead)", NULL},
{"texture", (getter)UISprite::get_texture, (setter)UISprite::set_texture, "Texture object", NULL},
- {"click", (getter)UIDrawable::get_click, (setter)UIDrawable::set_click,
- MCRF_PROPERTY(click,
- "Callable executed when object is clicked. "
- "Function receives (x, y) coordinates of click."
- ), (void*)PyObjectsEnum::UISPRITE},
- {"z_index", (getter)UIDrawable::get_int, (setter)UIDrawable::set_int,
- MCRF_PROPERTY(z_index,
- "Z-order for rendering (lower values rendered first). "
- "Automatically triggers scene resort when changed."
- ), (void*)PyObjectsEnum::UISPRITE},
+ {"click", (getter)UIDrawable::get_click, (setter)UIDrawable::set_click, "Object called with (x, y, button) when clicked", (void*)PyObjectsEnum::UISPRITE},
+ {"z_index", (getter)UIDrawable::get_int, (setter)UIDrawable::set_int, "Z-order for rendering (lower values rendered first)", (void*)PyObjectsEnum::UISPRITE},
{"name", (getter)UIDrawable::get_name, (setter)UIDrawable::set_name, "Name for finding elements", (void*)PyObjectsEnum::UISPRITE},
{"pos", (getter)UIDrawable::get_pos, (setter)UIDrawable::set_pos, "Position as a Vector", (void*)PyObjectsEnum::UISPRITE},
UIDRAWABLE_GETSETTERS,
diff --git a/tools/generate_api_docs.py b/tools/generate_api_docs.py
new file mode 100644
index 0000000..d1e100f
--- /dev/null
+++ b/tools/generate_api_docs.py
@@ -0,0 +1,482 @@
+#!/usr/bin/env python3
+"""Generate API reference documentation for McRogueFace.
+
+This script generates comprehensive API documentation in multiple formats:
+- Markdown for GitHub/documentation sites
+- HTML for local browsing
+- RST for Sphinx integration (future)
+"""
+
+import os
+import sys
+import inspect
+import datetime
+from typing import Dict, List, Any, Optional
+from pathlib import Path
+
+# We need to run this with McRogueFace as the interpreter
+# so mcrfpy is available
+import mcrfpy
+
+def escape_markdown(text: str) -> str:
+ """Escape special markdown characters."""
+ if not text:
+ return ""
+ # Escape backticks in inline code
+ return text.replace("`", "\\`")
+
+def format_signature(name: str, doc: str) -> str:
+ """Extract and format function signature from docstring."""
+ if not doc:
+ return f"{name}(...)"
+
+ lines = doc.strip().split('\n')
+ if lines and '(' in lines[0]:
+ # First line contains signature
+ return lines[0].split('->')[0].strip()
+
+ return f"{name}(...)"
+
+def get_class_info(cls: type) -> Dict[str, Any]:
+ """Extract comprehensive information about a class."""
+ info = {
+ 'name': cls.__name__,
+ 'doc': cls.__doc__ or "",
+ 'methods': [],
+ 'properties': [],
+ 'bases': [base.__name__ for base in cls.__bases__ if base.__name__ != 'object'],
+ }
+
+ # Get all attributes
+ for attr_name in sorted(dir(cls)):
+ if attr_name.startswith('_') and not attr_name.startswith('__'):
+ continue
+
+ try:
+ attr = getattr(cls, attr_name)
+
+ if isinstance(attr, property):
+ prop_info = {
+ 'name': attr_name,
+ 'doc': (attr.fget.__doc__ if attr.fget else "") or "",
+ 'readonly': attr.fset is None
+ }
+ info['properties'].append(prop_info)
+ elif callable(attr) and not attr_name.startswith('__'):
+ method_info = {
+ 'name': attr_name,
+ 'doc': attr.__doc__ or "",
+ 'signature': format_signature(attr_name, attr.__doc__)
+ }
+ info['methods'].append(method_info)
+ except:
+ pass
+
+ return info
+
+def get_function_info(func: Any, name: str) -> Dict[str, Any]:
+ """Extract information about a function."""
+ return {
+ 'name': name,
+ 'doc': func.__doc__ or "",
+ 'signature': format_signature(name, func.__doc__)
+ }
+
+def generate_markdown_class(cls_info: Dict[str, Any]) -> List[str]:
+ """Generate markdown documentation for a class."""
+ lines = []
+
+ # Class header
+ lines.append(f"### class `{cls_info['name']}`")
+ if cls_info['bases']:
+ lines.append(f"*Inherits from: {', '.join(cls_info['bases'])}*")
+ lines.append("")
+
+ # Class description
+ if cls_info['doc']:
+ doc_lines = cls_info['doc'].strip().split('\n')
+ # First line is usually the constructor signature
+ if doc_lines and '(' in doc_lines[0]:
+ lines.append(f"```python")
+ lines.append(doc_lines[0])
+ lines.append("```")
+ lines.append("")
+ # Rest is description
+ if len(doc_lines) > 2:
+ lines.extend(doc_lines[2:])
+ lines.append("")
+ else:
+ lines.extend(doc_lines)
+ lines.append("")
+
+ # Properties
+ if cls_info['properties']:
+ lines.append("#### Properties")
+ lines.append("")
+ for prop in cls_info['properties']:
+ readonly = " *(readonly)*" if prop['readonly'] else ""
+ lines.append(f"- **`{prop['name']}`**{readonly}")
+ if prop['doc']:
+ lines.append(f" - {prop['doc'].strip()}")
+ lines.append("")
+
+ # Methods
+ if cls_info['methods']:
+ lines.append("#### Methods")
+ lines.append("")
+ for method in cls_info['methods']:
+ lines.append(f"##### `{method['signature']}`")
+ if method['doc']:
+ # Parse docstring for better formatting
+ doc_lines = method['doc'].strip().split('\n')
+ # Skip the signature line if it's repeated
+ start = 1 if doc_lines and method['name'] in doc_lines[0] else 0
+ for line in doc_lines[start:]:
+ lines.append(line)
+ lines.append("")
+
+ lines.append("---")
+ lines.append("")
+ return lines
+
+def generate_markdown_function(func_info: Dict[str, Any]) -> List[str]:
+ """Generate markdown documentation for a function."""
+ lines = []
+
+ lines.append(f"### `{func_info['signature']}`")
+ lines.append("")
+
+ if func_info['doc']:
+ doc_lines = func_info['doc'].strip().split('\n')
+ # Skip signature line if present
+ start = 1 if doc_lines and func_info['name'] in doc_lines[0] else 0
+
+ # Process documentation sections
+ in_section = None
+ for line in doc_lines[start:]:
+ if line.strip() in ['Args:', 'Returns:', 'Raises:', 'Note:', 'Example:']:
+ in_section = line.strip()
+ lines.append(f"**{in_section}**")
+ elif in_section and line.strip():
+ # Indent content under sections
+ lines.append(f"{line}")
+ else:
+ lines.append(line)
+ lines.append("")
+
+ lines.append("---")
+ lines.append("")
+ return lines
+
+def generate_markdown_docs() -> str:
+ """Generate complete markdown API documentation."""
+ lines = []
+
+ # Header
+ lines.append("# McRogueFace API Reference")
+ lines.append("")
+ lines.append(f"*Generated on {datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')}*")
+ lines.append("")
+
+ # Module description
+ if mcrfpy.__doc__:
+ lines.append("## Overview")
+ lines.append("")
+ lines.extend(mcrfpy.__doc__.strip().split('\n'))
+ lines.append("")
+
+ # Table of contents
+ lines.append("## Table of Contents")
+ lines.append("")
+ lines.append("- [Classes](#classes)")
+ lines.append("- [Functions](#functions)")
+ lines.append("- [Automation Module](#automation-module)")
+ lines.append("")
+
+ # Collect all components
+ classes = []
+ functions = []
+ constants = []
+
+ for name in sorted(dir(mcrfpy)):
+ if name.startswith('_'):
+ continue
+
+ obj = getattr(mcrfpy, name)
+
+ if isinstance(obj, type):
+ classes.append((name, obj))
+ elif callable(obj):
+ functions.append((name, obj))
+ elif not inspect.ismodule(obj):
+ constants.append((name, obj))
+
+ # Document classes
+ lines.append("## Classes")
+ lines.append("")
+
+ # Group classes by category
+ ui_classes = []
+ collection_classes = []
+ system_classes = []
+ other_classes = []
+
+ for name, cls in classes:
+ if name in ['Frame', 'Caption', 'Sprite', 'Grid', 'Entity']:
+ ui_classes.append((name, cls))
+ elif 'Collection' in name:
+ collection_classes.append((name, cls))
+ elif name in ['Color', 'Vector', 'Texture', 'Font']:
+ system_classes.append((name, cls))
+ else:
+ other_classes.append((name, cls))
+
+ # UI Classes
+ if ui_classes:
+ lines.append("### UI Components")
+ lines.append("")
+ for name, cls in ui_classes:
+ lines.extend(generate_markdown_class(get_class_info(cls)))
+
+ # Collections
+ if collection_classes:
+ lines.append("### Collections")
+ lines.append("")
+ for name, cls in collection_classes:
+ lines.extend(generate_markdown_class(get_class_info(cls)))
+
+ # System Classes
+ if system_classes:
+ lines.append("### System Types")
+ lines.append("")
+ for name, cls in system_classes:
+ lines.extend(generate_markdown_class(get_class_info(cls)))
+
+ # Other Classes
+ if other_classes:
+ lines.append("### Other Classes")
+ lines.append("")
+ for name, cls in other_classes:
+ lines.extend(generate_markdown_class(get_class_info(cls)))
+
+ # Document functions
+ lines.append("## Functions")
+ lines.append("")
+
+ # Group functions by category
+ scene_funcs = []
+ audio_funcs = []
+ ui_funcs = []
+ system_funcs = []
+
+ for name, func in functions:
+ if 'scene' in name.lower() or name in ['createScene', 'setScene']:
+ scene_funcs.append((name, func))
+ elif any(x in name.lower() for x in ['sound', 'music', 'volume']):
+ audio_funcs.append((name, func))
+ elif name in ['find', 'findAll']:
+ ui_funcs.append((name, func))
+ else:
+ system_funcs.append((name, func))
+
+ # Scene Management
+ if scene_funcs:
+ lines.append("### Scene Management")
+ lines.append("")
+ for name, func in scene_funcs:
+ lines.extend(generate_markdown_function(get_function_info(func, name)))
+
+ # Audio
+ if audio_funcs:
+ lines.append("### Audio")
+ lines.append("")
+ for name, func in audio_funcs:
+ lines.extend(generate_markdown_function(get_function_info(func, name)))
+
+ # UI Utilities
+ if ui_funcs:
+ lines.append("### UI Utilities")
+ lines.append("")
+ for name, func in ui_funcs:
+ lines.extend(generate_markdown_function(get_function_info(func, name)))
+
+ # System
+ if system_funcs:
+ lines.append("### System")
+ lines.append("")
+ for name, func in system_funcs:
+ lines.extend(generate_markdown_function(get_function_info(func, name)))
+
+ # Automation module
+ if hasattr(mcrfpy, 'automation'):
+ lines.append("## Automation Module")
+ lines.append("")
+ lines.append("The `mcrfpy.automation` module provides testing and automation capabilities.")
+ lines.append("")
+
+ automation = mcrfpy.automation
+ auto_funcs = []
+
+ for name in sorted(dir(automation)):
+ if not name.startswith('_'):
+ obj = getattr(automation, name)
+ if callable(obj):
+ auto_funcs.append((name, obj))
+
+ for name, func in auto_funcs:
+ # Format as static method
+ func_info = get_function_info(func, name)
+ lines.append(f"### `automation.{func_info['signature']}`")
+ lines.append("")
+ if func_info['doc']:
+ lines.append(func_info['doc'])
+ lines.append("")
+ lines.append("---")
+ lines.append("")
+
+ return '\n'.join(lines)
+
+def generate_html_docs(markdown_content: str) -> str:
+ """Convert markdown to HTML."""
+ # Simple conversion - in production use a proper markdown parser
+ html = ['']
+ html.append('')
+ html.append('')
+ html.append('McRogueFace API Reference')
+ html.append('')
+ html.append('')
+
+ # Very basic markdown to HTML conversion
+ lines = markdown_content.split('\n')
+ in_code_block = False
+ in_list = False
+
+ for line in lines:
+ stripped = line.strip()
+
+ if stripped.startswith('```'):
+ if in_code_block:
+ html.append('')
+ in_code_block = False
+ else:
+ lang = stripped[3:] or 'python'
+ html.append(f'')
+ in_code_block = True
+ continue
+
+ if in_code_block:
+ html.append(line)
+ continue
+
+ # Headers
+ if stripped.startswith('#'):
+ level = len(stripped.split()[0])
+ text = stripped[level:].strip()
+ html.append(f'{text}')
+ # Lists
+ elif stripped.startswith('- '):
+ if not in_list:
+ html.append('')
+ in_list = True
+ html.append(f'- {stripped[2:]}
')
+ # Horizontal rule
+ elif stripped == '---':
+ if in_list:
+ html.append('
')
+ in_list = False
+ html.append('
')
+ # Emphasis
+ elif stripped.startswith('*') and stripped.endswith('*') and len(stripped) > 2:
+ html.append(f'{stripped[1:-1]}')
+ # Bold
+ elif stripped.startswith('**') and stripped.endswith('**'):
+ html.append(f'{stripped[2:-2]}')
+ # Regular paragraph
+ elif stripped:
+ if in_list:
+ html.append('')
+ in_list = False
+ # Convert inline code
+ text = stripped
+ if '`' in text:
+ import re
+ text = re.sub(r'`([^`]+)`', r'\1', text)
+ html.append(f'{text}
')
+ else:
+ if in_list:
+ html.append('')
+ in_list = False
+ # Empty line
+ html.append('')
+
+ if in_list:
+ html.append('')
+ if in_code_block:
+ html.append('
')
+
+ html.append('')
+ return '\n'.join(html)
+
+def main():
+ """Generate API documentation in multiple formats."""
+ print("Generating McRogueFace API Documentation...")
+
+ # Create docs directory
+ docs_dir = Path("docs")
+ docs_dir.mkdir(exist_ok=True)
+
+ # Generate markdown documentation
+ print("- Generating Markdown documentation...")
+ markdown_content = generate_markdown_docs()
+
+ # Write markdown
+ md_path = docs_dir / "API_REFERENCE.md"
+ with open(md_path, 'w') as f:
+ f.write(markdown_content)
+ print(f" ✓ Written to {md_path}")
+
+ # Generate HTML
+ print("- Generating HTML documentation...")
+ html_content = generate_html_docs(markdown_content)
+
+ # Write HTML
+ html_path = docs_dir / "api_reference.html"
+ with open(html_path, 'w') as f:
+ f.write(html_content)
+ print(f" ✓ Written to {html_path}")
+
+ # Summary statistics
+ lines = markdown_content.split('\n')
+ class_count = markdown_content.count('### class')
+ func_count = len([l for l in lines if l.strip().startswith('### `') and 'class' not in l])
+
+ print("\nDocumentation Statistics:")
+ print(f"- Classes documented: {class_count}")
+ print(f"- Functions documented: {func_count}")
+ print(f"- Total lines: {len(lines)}")
+ print(f"- File size: {len(markdown_content):,} bytes")
+
+ print("\nAPI documentation generated successfully!")
+
+if __name__ == '__main__':
+ main()
\ No newline at end of file
diff --git a/tools/generate_api_docs_html.py b/tools/generate_api_docs_html.py
new file mode 100644
index 0000000..fe3cf08
--- /dev/null
+++ b/tools/generate_api_docs_html.py
@@ -0,0 +1,1602 @@
+#!/usr/bin/env python3
+"""Generate high-quality HTML API reference documentation for McRogueFace."""
+
+import os
+import sys
+import datetime
+import html
+from pathlib import Path
+import mcrfpy
+
+def escape_html(text: str) -> str:
+ """Escape HTML special characters."""
+ return html.escape(text) if text else ""
+
+def format_docstring_as_html(docstring: str) -> str:
+ """Convert docstring to properly formatted HTML."""
+ if not docstring:
+ return ""
+
+ # Split and process lines
+ lines = docstring.strip().split('\n')
+ result = []
+ in_code_block = False
+
+ for line in lines:
+ # Convert \n to actual newlines
+ line = line.replace('\\n', '\n')
+
+ # Handle code blocks
+ if line.strip().startswith('```'):
+ if in_code_block:
+ result.append('')
+ in_code_block = False
+ else:
+ result.append('')
+ in_code_block = True
+ continue
+
+ # Convert markdown-style code to HTML
+ if '`' in line and not in_code_block:
+ import re
+ line = re.sub(r'`([^`]+)`', r'\1', line)
+
+ if in_code_block:
+ result.append(escape_html(line))
+ else:
+ result.append(escape_html(line) + '
')
+
+ if in_code_block:
+ result.append('
')
+ html_parts.append(f'
class {class_name}
')
+
+ # Inheritance
+ if cls_info['bases']:
+ html_parts.append(f'
Inherits from: {", ".join(cls_info["bases"])}
')
+
+ # Get additional documentation
+ init_info = generate_class_init_docs(class_name)
+ collection_info = generate_collection_docs(class_name)
+
+ # Constructor signature for classes with __init__
+ if init_info.get('signature'):
+ html_parts.append('
')
+ html_parts.append('
')
+ html_parts.append(escape_html(init_info['signature']))
+ html_parts.append('
')
+ html_parts.append('
')
+
+ # Description
+ description = ""
+ if collection_info.get('description'):
+ description = collection_info['description']
+ elif init_info.get('description'):
+ description = init_info['description']
+ elif cls_info['doc']:
+ # Parse description from docstring
+ doc_lines = cls_info['doc'].strip().split('\n')
+ # Skip constructor line if present
+ start_idx = 1 if doc_lines and '(' in doc_lines[0] else 0
+ if start_idx < len(doc_lines):
+ description = '\n'.join(doc_lines[start_idx:]).strip()
+
+ if description:
+ html_parts.append('
')
+ html_parts.append(f'
{format_docstring_as_html(description)}
')
+ html_parts.append('
')
+
+ # Constructor arguments
+ if init_info.get('args'):
+ html_parts.append('
')
+ html_parts.append('
Arguments:
')
+ html_parts.append('
')
+ for arg_name, arg_type, arg_desc in init_info['args']:
+ html_parts.append(f'{arg_name} ({arg_type})- {escape_html(arg_desc)}
')
+ html_parts.append('
')
+ html_parts.append('
')
+
+ # Properties/Attributes
+ props = cls_info.get('properties', {})
+ if props or init_info.get('properties'):
+ html_parts.append('
')
+ html_parts.append('
Attributes:
')
+ html_parts.append('
')
+
+ # Add documented properties from init_info
+ if init_info.get('properties'):
+ for prop_name in init_info['properties']:
+ html_parts.append(f'{prop_name}- Property of {class_name}
')
+
+ # Add actual properties
+ for prop_name, prop_info in props.items():
+ readonly = ' (read-only)' if prop_info.get('readonly') else ''
+ html_parts.append(f'{prop_name}{readonly}- {escape_html(prop_info["doc"])}
')
+
+ html_parts.append('
')
+ html_parts.append('
')
+
+ # Methods
+ methods = cls_info.get('methods', {})
+ collection_methods = collection_info.get('methods', {})
+
+ if methods or collection_methods:
+ html_parts.append('
')
+ html_parts.append('
Methods:
')
+
+ for method_name, method_doc in {**collection_methods, **methods}.items():
+ if method_name == '__init__':
+ continue
+
+ html_parts.append('
')
+
+ # Get specific method documentation
+ method_info = generate_method_docs(method_name, class_name)
+
+ if method_info:
+ # Use detailed documentation
+ html_parts.append(f'
{method_info["signature"]}
')
+ html_parts.append(f'
{escape_html(method_info["description"])}
')
+
+ if method_info.get('args'):
+ html_parts.append('
Arguments:
')
+ html_parts.append('
')
+ for arg in method_info['args']:
+ if len(arg) == 3:
+ html_parts.append(f'{arg[0]} ({arg[1]}): {arg[2]}{arg[0]} ({arg[1]})
')
+
+ if method_info.get('returns'):
+ html_parts.append(f'
Returns: {escape_html(method_info["returns"])}
')
+
+ if method_info.get('note'):
+ html_parts.append(f'
Note: {escape_html(method_info["note"])}
')
+ else:
+ # Use docstring
+ html_parts.append(f'
{method_name}(...)
')
+ if isinstance(method_doc, str) and method_doc:
+ html_parts.append(f'
{escape_html(method_doc)}
')
+
+ html_parts.append('
')
+
+ html_parts.append('
')
+
+ # Example
+ if init_info.get('example'):
+ html_parts.append('
')
+ html_parts.append('
Example:
')
+ html_parts.append('
')
+ html_parts.append(escape_html(init_info['example']))
+ html_parts.append('
')
+ html_parts.append('
')
+
+ html_parts.append('
')
+
+ return '\n'.join(html_parts)
+
+def generate_html_documentation():
+ """Generate complete HTML API documentation."""
+ html_parts = []
+
+ # HTML header
+ html_parts.append('''
+
+
+
+
+ McRogueFace API Reference
+
+
+
+
+''')
+
+ # Title and timestamp
+ html_parts.append('
McRogueFace API Reference
')
+ html_parts.append(f'
Generated on {datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")}
')
+
+ # Overview
+ if mcrfpy.__doc__:
+ html_parts.append('
')
+ html_parts.append('
Overview
')
+ # Process the docstring properly
+ doc_lines = mcrfpy.__doc__.strip().split('\\n')
+ for line in doc_lines:
+ if line.strip().startswith('Example:'):
+ html_parts.append('
Example:
')
+ html_parts.append('
')
+ elif line.strip() and not line.startswith(' '):
+ html_parts.append(f'{escape_html(line)}
')
+ elif line.strip():
+ # Code line
+ html_parts.append(escape_html(line))
+ html_parts.append('
')
+ html_parts.append('
')
+
+ # Table of Contents
+ html_parts.append('
')
+ html_parts.append('
Table of Contents
')
+ html_parts.append('
')
+ html_parts.append('- Classes')
+ html_parts.append('')
+ html_parts.append('
')
+ html_parts.append('- Functions')
+ html_parts.append('')
+ html_parts.append('
')
+ html_parts.append('- Automation Module
')
+ html_parts.append('
')
+ html_parts.append('
')
+
+ # Collect all components
+ classes = {}
+ functions = {}
+
+ for name in sorted(dir(mcrfpy)):
+ if name.startswith('_'):
+ continue
+
+ obj = getattr(mcrfpy, name)
+
+ if isinstance(obj, type):
+ classes[name] = obj
+ elif callable(obj) and not isinstance(obj, type):
+ # Include built-in functions and other callables (but not classes)
+ functions[name] = obj
+
+
+ # Classes section
+ html_parts.append('
Classes
')
+
+ # Group classes
+ ui_classes = ['Frame', 'Caption', 'Sprite', 'Grid', 'Entity']
+ collection_classes = ['EntityCollection', 'UICollection', 'UICollectionIter', 'UIEntityCollectionIter']
+ system_classes = ['Color', 'Vector', 'Texture', 'Font']
+ other_classes = [name for name in classes if name not in ui_classes + collection_classes + system_classes]
+
+ # UI Components
+ html_parts.append('
UI Components
')
+ for class_name in ui_classes:
+ if class_name in classes:
+ cls_info = get_class_details(classes[class_name])
+ html_parts.append(format_class_html(cls_info, class_name))
+
+ # Collections
+ html_parts.append('
Collections
')
+ for class_name in collection_classes:
+ if class_name in classes:
+ cls_info = get_class_details(classes[class_name])
+ html_parts.append(format_class_html(cls_info, class_name))
+
+ # System Types
+ html_parts.append('
System Types
')
+ for class_name in system_classes:
+ if class_name in classes:
+ cls_info = get_class_details(classes[class_name])
+ html_parts.append(format_class_html(cls_info, class_name))
+
+ # Other Classes
+ html_parts.append('
Other Classes
')
+ for class_name in other_classes:
+ if class_name in classes:
+ cls_info = get_class_details(classes[class_name])
+ html_parts.append(format_class_html(cls_info, class_name))
+
+ # Functions section
+ html_parts.append('
Functions
')
+
+ # Group functions by category
+ scene_funcs = ['createScene', 'setScene', 'currentScene', 'sceneUI', 'keypressScene']
+ audio_funcs = ['createSoundBuffer', 'loadMusic', 'playSound', 'getMusicVolume',
+ 'getSoundVolume', 'setMusicVolume', 'setSoundVolume']
+ ui_funcs = ['find', 'findAll']
+ system_funcs = ['exit', 'getMetrics', 'setTimer', 'delTimer', 'setScale']
+
+ # Scene Management
+ html_parts.append('
Scene Management
')
+ for func_name in scene_funcs:
+ if func_name in functions:
+ html_parts.append(format_function_html(func_name, functions[func_name]))
+
+ # Audio
+ html_parts.append('
Audio
')
+ for func_name in audio_funcs:
+ if func_name in functions:
+ html_parts.append(format_function_html(func_name, functions[func_name]))
+
+ # UI Utilities
+ html_parts.append('
UI Utilities
')
+ for func_name in ui_funcs:
+ if func_name in functions:
+ html_parts.append(format_function_html(func_name, functions[func_name]))
+
+ # System
+ html_parts.append('
System
')
+ for func_name in system_funcs:
+ if func_name in functions:
+ html_parts.append(format_function_html(func_name, functions[func_name]))
+
+ # Automation Module
+ if hasattr(mcrfpy, 'automation'):
+ html_parts.append('
')
+ html_parts.append('
Automation Module
')
+ html_parts.append('
The mcrfpy.automation module provides testing and automation capabilities for simulating user input and capturing screenshots.
')
+
+ automation = mcrfpy.automation
+ auto_funcs = []
+
+ for name in sorted(dir(automation)):
+ if not name.startswith('_'):
+ obj = getattr(automation, name)
+ if callable(obj):
+ auto_funcs.append((name, obj))
+
+ for name, func in auto_funcs:
+ html_parts.append('
')
+ html_parts.append(f'
automation.{name}
')
+ if func.__doc__:
+ # Extract just the description, not the repeated signature
+ doc_lines = func.__doc__.strip().split(' - ')
+ if len(doc_lines) > 1:
+ description = doc_lines[1]
+ else:
+ description = func.__doc__.strip()
+ html_parts.append(f'
{escape_html(description)}
')
+ html_parts.append('
')
+
+ html_parts.append('
')
+
+ # Close HTML
+ html_parts.append('''
+
')
+
+ # Get enhanced documentation
+ func_docs = generate_function_docs()
+
+ if func_name in func_docs:
+ doc_info = func_docs[func_name]
+
+ # Signature
+ signature = doc_info.get('signature', f'{func_name}(...)')
+ html_parts.append(f'
{escape_html(signature)}
')
+
+ # Description
+ if 'description' in doc_info:
+ html_parts.append(f'
{escape_html(doc_info["description"])}
')
+
+ # Arguments
+ if 'args' in doc_info and doc_info['args']:
+ html_parts.append('
')
+ html_parts.append('
Arguments:
')
+ html_parts.append('
')
+ for arg_name, arg_type, arg_desc in doc_info['args']:
+ html_parts.append(f'{escape_html(arg_name)} : {escape_html(arg_type)}- {escape_html(arg_desc)}
')
+ html_parts.append('
')
+ html_parts.append('
')
+
+ # Returns
+ if 'returns' in doc_info and doc_info['returns']:
+ html_parts.append('
')
+ html_parts.append('
Returns:
')
+ html_parts.append(f'
{escape_html(doc_info["returns"])}
')
+ html_parts.append('
')
+
+ # Exceptions
+ if 'exceptions' in doc_info and doc_info['exceptions']:
+ html_parts.append('
')
+ html_parts.append('
Raises:
')
+ html_parts.append('
')
+ for exc_type, exc_desc in doc_info['exceptions']:
+ html_parts.append(f'{escape_html(exc_type)}- {escape_html(exc_desc)}
')
+ html_parts.append('
')
+ html_parts.append('
')
+
+ # Note
+ if 'note' in doc_info:
+ html_parts.append('
')
+ html_parts.append(f'
Note: {escape_html(doc_info["note"])}
')
+ html_parts.append('
')
+
+ # Example
+ if 'example' in doc_info:
+ html_parts.append('
')
+ html_parts.append('
Example:
')
+ html_parts.append('
')
+ html_parts.append(escape_html(doc_info['example']))
+ html_parts.append('
')
+ html_parts.append('
')
+ else:
+ # Fallback to parsing docstring if not in enhanced docs
+ doc = func.__doc__ or ""
+ lines = doc.strip().split('\n') if doc else []
+
+ # Extract signature
+ signature = func_name + '(...)'
+ if lines and '(' in lines[0]:
+ signature = lines[0].strip()
+
+ html_parts.append(f'
{escape_html(signature)}
')
+
+ # Process rest of docstring
+ if len(lines) > 1:
+ in_section = None
+ for line in lines[1:]:
+ stripped = line.strip()
+
+ if stripped in ['Args:', 'Returns:', 'Raises:', 'Note:', 'Example:']:
+ in_section = stripped[:-1]
+ html_parts.append(f'
{in_section}:
')
+ elif in_section == 'Example':
+ if not stripped:
+ continue
+ if stripped.startswith('>>>') or (len(lines) > lines.index(line) + 1 and
+ lines[lines.index(line) + 1].strip().startswith('>>>')):
+ html_parts.append('
')
+ html_parts.append(escape_html(stripped))
+ # Get rest of example
+ idx = lines.index(line) + 1
+ while idx < len(lines) and lines[idx].strip():
+ html_parts.append(escape_html(lines[idx]))
+ idx += 1
+ html_parts.append('
')
+ break
+ elif in_section and stripped:
+ if in_section == 'Args':
+ # Format arguments nicely
+ if ':' in stripped:
+ param, desc = stripped.split(':', 1)
+ html_parts.append(f'
{escape_html(param.strip())}: {escape_html(desc.strip())}
')
+ else:
+ html_parts.append(f'
{escape_html(stripped)}
')
+ else:
+ html_parts.append(f'
{escape_html(stripped)}
')
+ elif stripped and not in_section:
+ html_parts.append(f'
{escape_html(stripped)}
')
+
+ html_parts.append('
')
+
+ return '\n'.join(html_parts)
+
+def main():
+ """Generate improved HTML API documentation."""
+ print("Generating improved HTML API documentation...")
+
+ # Generate HTML
+ html_content = generate_html_documentation()
+
+ # Write to file
+ output_path = Path("docs/api_reference_improved.html")
+ output_path.parent.mkdir(exist_ok=True)
+
+ with open(output_path, 'w', encoding='utf-8') as f:
+ f.write(html_content)
+
+ print(f"✓ Generated {output_path}")
+ print(f" File size: {len(html_content):,} bytes")
+
+ # Also generate a test to verify the HTML
+ test_content = '''#!/usr/bin/env python3
+"""Test the improved HTML API documentation."""
+
+import os
+import sys
+from pathlib import Path
+
+def test_html_quality():
+ """Test that the HTML documentation meets quality standards."""
+ html_path = Path("docs/api_reference_improved.html")
+
+ if not html_path.exists():
+ print("ERROR: HTML documentation not found")
+ return False
+
+ with open(html_path, 'r') as f:
+ content = f.read()
+
+ # Check for common issues
+ issues = []
+
+ # Check that \\n is not present literally
+ if '\\\\n' in content:
+ issues.append("Found literal \\\\n in HTML content")
+
+ # Check that markdown links are converted
+ if '[' in content and '](#' in content:
+ issues.append("Found unconverted markdown links")
+
+ # Check for proper HTML structure
+ if 'Args:
' in content:
+ issues.append("Args: should not be an H4 heading")
+
+ if 'Attributes:
' not in content:
+ issues.append("Missing proper Attributes: headings")
+
+ # Check for duplicate method descriptions
+ if content.count('Get bounding box as (x, y, width, height)') > 20:
+ issues.append("Too many duplicate method descriptions")
+
+ # Check specific improvements
+ if 'Entity' in content and 'Inherits from: Drawable' in content:
+ issues.append("Entity incorrectly shown as inheriting from Drawable")
+
+ if not issues:
+ print("✓ HTML documentation passes all quality checks")
+ return True
+ else:
+ print("Issues found:")
+ for issue in issues:
+ print(f" - {issue}")
+ return False
+
+if __name__ == '__main__':
+ if test_html_quality():
+ print("PASS")
+ sys.exit(0)
+ else:
+ print("FAIL")
+ sys.exit(1)
+'''
+
+ test_path = Path("tests/test_html_quality.py")
+ with open(test_path, 'w') as f:
+ f.write(test_content)
+
+ print(f"✓ Generated test at {test_path}")
+
+if __name__ == '__main__':
+ main()
\ No newline at end of file
diff --git a/tools/generate_api_docs_simple.py b/tools/generate_api_docs_simple.py
new file mode 100644
index 0000000..2bb405f
--- /dev/null
+++ b/tools/generate_api_docs_simple.py
@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""Generate API reference documentation for McRogueFace - Simple version."""
+
+import os
+import sys
+import datetime
+from pathlib import Path
+
+import mcrfpy
+
+def generate_markdown_docs():
+ """Generate markdown API documentation."""
+ lines = []
+
+ # Header
+ lines.append("# McRogueFace API Reference")
+ lines.append("")
+ lines.append("*Generated on {}*".format(datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')))
+ lines.append("")
+
+ # Module description
+ if mcrfpy.__doc__:
+ lines.append("## Overview")
+ lines.append("")
+ lines.extend(mcrfpy.__doc__.strip().split('\n'))
+ lines.append("")
+
+ # Collect all components
+ classes = []
+ functions = []
+
+ for name in sorted(dir(mcrfpy)):
+ if name.startswith('_'):
+ continue
+
+ obj = getattr(mcrfpy, name)
+
+ if isinstance(obj, type):
+ classes.append((name, obj))
+ elif callable(obj):
+ functions.append((name, obj))
+
+ # Document classes
+ lines.append("## Classes")
+ lines.append("")
+
+ for name, cls in classes:
+ lines.append("### class {}".format(name))
+ if cls.__doc__:
+ doc_lines = cls.__doc__.strip().split('\n')
+ for line in doc_lines[:5]: # First 5 lines
+ lines.append(line)
+ lines.append("")
+ lines.append("---")
+ lines.append("")
+
+ # Document functions
+ lines.append("## Functions")
+ lines.append("")
+
+ for name, func in functions:
+ lines.append("### {}".format(name))
+ if func.__doc__:
+ doc_lines = func.__doc__.strip().split('\n')
+ for line in doc_lines[:5]: # First 5 lines
+ lines.append(line)
+ lines.append("")
+ lines.append("---")
+ lines.append("")
+
+ # Automation module
+ if hasattr(mcrfpy, 'automation'):
+ lines.append("## Automation Module")
+ lines.append("")
+
+ automation = mcrfpy.automation
+ for name in sorted(dir(automation)):
+ if not name.startswith('_'):
+ obj = getattr(automation, name)
+ if callable(obj):
+ lines.append("### automation.{}".format(name))
+ if obj.__doc__:
+ lines.append(obj.__doc__.strip().split('\n')[0])
+ lines.append("")
+
+ return '\n'.join(lines)
+
+def main():
+ """Generate API documentation."""
+ print("Generating McRogueFace API Documentation...")
+
+ # Create docs directory
+ docs_dir = Path("docs")
+ docs_dir.mkdir(exist_ok=True)
+
+ # Generate markdown
+ markdown_content = generate_markdown_docs()
+
+ # Write markdown
+ md_path = docs_dir / "API_REFERENCE.md"
+ with open(md_path, 'w') as f:
+ f.write(markdown_content)
+ print("Written to {}".format(md_path))
+
+ # Summary
+ lines = markdown_content.split('\n')
+ class_count = markdown_content.count('### class')
+ func_count = markdown_content.count('### ') - class_count - markdown_content.count('### automation.')
+
+ print("\nDocumentation Statistics:")
+ print("- Classes documented: {}".format(class_count))
+ print("- Functions documented: {}".format(func_count))
+ print("- Total lines: {}".format(len(lines)))
+
+ print("\nAPI documentation generated successfully!")
+ sys.exit(0)
+
+if __name__ == '__main__':
+ main()
\ No newline at end of file
diff --git a/tools/generate_complete_api_docs.py b/tools/generate_complete_api_docs.py
new file mode 100644
index 0000000..8b41446
--- /dev/null
+++ b/tools/generate_complete_api_docs.py
@@ -0,0 +1,960 @@
+#!/usr/bin/env python3
+"""Generate COMPLETE HTML API reference documentation for McRogueFace with NO missing methods."""
+
+import os
+import sys
+import datetime
+import html
+from pathlib import Path
+import mcrfpy
+
+def escape_html(text: str) -> str:
+ """Escape HTML special characters."""
+ return html.escape(text) if text else ""
+
+def get_complete_method_documentation():
+ """Return complete documentation for ALL methods across all classes."""
+ return {
+ # Base Drawable methods (inherited by all UI elements)
+ 'Drawable': {
+ 'get_bounds': {
+ 'signature': 'get_bounds()',
+ 'description': 'Get the bounding rectangle of this drawable element.',
+ 'returns': 'tuple: (x, y, width, height) representing the element\'s bounds',
+ 'note': 'The bounds are in screen coordinates and account for current position and size.'
+ },
+ 'move': {
+ 'signature': 'move(dx, dy)',
+ 'description': 'Move the element by a relative offset.',
+ 'args': [
+ ('dx', 'float', 'Horizontal offset in pixels'),
+ ('dy', 'float', 'Vertical offset in pixels')
+ ],
+ 'note': 'This modifies the x and y position properties by the given amounts.'
+ },
+ 'resize': {
+ 'signature': 'resize(width, height)',
+ 'description': 'Resize the element to new dimensions.',
+ 'args': [
+ ('width', 'float', 'New width in pixels'),
+ ('height', 'float', 'New height in pixels')
+ ],
+ 'note': 'For Caption and Sprite, this may not change actual size if determined by content.'
+ }
+ },
+
+ # Entity-specific methods
+ 'Entity': {
+ 'at': {
+ 'signature': 'at(x, y)',
+ 'description': 'Check if this entity is at the specified grid coordinates.',
+ 'args': [
+ ('x', 'int', 'Grid x coordinate to check'),
+ ('y', 'int', 'Grid y coordinate to check')
+ ],
+ 'returns': 'bool: True if entity is at position (x, y), False otherwise'
+ },
+ 'die': {
+ 'signature': 'die()',
+ 'description': 'Remove this entity from its parent grid.',
+ 'note': 'The entity object remains valid but is no longer rendered or updated.'
+ },
+ 'index': {
+ 'signature': 'index()',
+ 'description': 'Get the index of this entity in its parent grid\'s entity list.',
+ 'returns': 'int: Index position, or -1 if not in a grid'
+ }
+ },
+
+ # Grid-specific methods
+ 'Grid': {
+ 'at': {
+ 'signature': 'at(x, y)',
+ 'description': 'Get the GridPoint at the specified grid coordinates.',
+ 'args': [
+ ('x', 'int', 'Grid x coordinate'),
+ ('y', 'int', 'Grid y coordinate')
+ ],
+ 'returns': 'GridPoint or None: The grid point at (x, y), or None if out of bounds'
+ }
+ },
+
+ # Collection methods
+ 'EntityCollection': {
+ 'append': {
+ 'signature': 'append(entity)',
+ 'description': 'Add an entity to the end of the collection.',
+ 'args': [('entity', 'Entity', 'The entity to add')]
+ },
+ 'remove': {
+ 'signature': 'remove(entity)',
+ 'description': 'Remove the first occurrence of an entity from the collection.',
+ 'args': [('entity', 'Entity', 'The entity to remove')],
+ 'raises': 'ValueError: If entity is not in collection'
+ },
+ 'extend': {
+ 'signature': 'extend(iterable)',
+ 'description': 'Add all entities from an iterable to the collection.',
+ 'args': [('iterable', 'Iterable[Entity]', 'Entities to add')]
+ },
+ 'count': {
+ 'signature': 'count(entity)',
+ 'description': 'Count the number of occurrences of an entity in the collection.',
+ 'args': [('entity', 'Entity', 'The entity to count')],
+ 'returns': 'int: Number of times entity appears in collection'
+ },
+ 'index': {
+ 'signature': 'index(entity)',
+ 'description': 'Find the index of the first occurrence of an entity.',
+ 'args': [('entity', 'Entity', 'The entity to find')],
+ 'returns': 'int: Index of entity in collection',
+ 'raises': 'ValueError: If entity is not in collection'
+ }
+ },
+
+ 'UICollection': {
+ 'append': {
+ 'signature': 'append(drawable)',
+ 'description': 'Add a drawable element to the end of the collection.',
+ 'args': [('drawable', 'UIDrawable', 'The drawable element to add')]
+ },
+ 'remove': {
+ 'signature': 'remove(drawable)',
+ 'description': 'Remove the first occurrence of a drawable from the collection.',
+ 'args': [('drawable', 'UIDrawable', 'The drawable to remove')],
+ 'raises': 'ValueError: If drawable is not in collection'
+ },
+ 'extend': {
+ 'signature': 'extend(iterable)',
+ 'description': 'Add all drawables from an iterable to the collection.',
+ 'args': [('iterable', 'Iterable[UIDrawable]', 'Drawables to add')]
+ },
+ 'count': {
+ 'signature': 'count(drawable)',
+ 'description': 'Count the number of occurrences of a drawable in the collection.',
+ 'args': [('drawable', 'UIDrawable', 'The drawable to count')],
+ 'returns': 'int: Number of times drawable appears in collection'
+ },
+ 'index': {
+ 'signature': 'index(drawable)',
+ 'description': 'Find the index of the first occurrence of a drawable.',
+ 'args': [('drawable', 'UIDrawable', 'The drawable to find')],
+ 'returns': 'int: Index of drawable in collection',
+ 'raises': 'ValueError: If drawable is not in collection'
+ }
+ },
+
+ # Animation methods
+ 'Animation': {
+ 'get_current_value': {
+ 'signature': 'get_current_value()',
+ 'description': 'Get the current interpolated value of the animation.',
+ 'returns': 'float: Current animation value between start and end'
+ },
+ 'start': {
+ 'signature': 'start(target)',
+ 'description': 'Start the animation on a target UI element.',
+ 'args': [('target', 'UIDrawable', 'The UI element to animate')],
+ 'note': 'The target must have the property specified in the animation constructor.'
+ },
+ 'update': {
+ 'signature': 'update(delta_time)',
+ 'description': 'Update the animation by the given time delta.',
+ 'args': [('delta_time', 'float', 'Time elapsed since last update in seconds')],
+ 'returns': 'bool: True if animation is still running, False if finished'
+ }
+ },
+
+ # Color methods
+ 'Color': {
+ 'from_hex': {
+ 'signature': 'from_hex(hex_string)',
+ 'description': 'Create a Color from a hexadecimal color string.',
+ 'args': [('hex_string', 'str', 'Hex color string (e.g., "#FF0000" or "FF0000")')],
+ 'returns': 'Color: New Color object from hex string',
+ 'example': 'red = Color.from_hex("#FF0000")'
+ },
+ 'to_hex': {
+ 'signature': 'to_hex()',
+ 'description': 'Convert this Color to a hexadecimal string.',
+ 'returns': 'str: Hex color string in format "#RRGGBB"',
+ 'example': 'hex_str = color.to_hex() # Returns "#FF0000"'
+ },
+ 'lerp': {
+ 'signature': 'lerp(other, t)',
+ 'description': 'Linearly interpolate between this color and another.',
+ 'args': [
+ ('other', 'Color', 'The color to interpolate towards'),
+ ('t', 'float', 'Interpolation factor from 0.0 to 1.0')
+ ],
+ 'returns': 'Color: New interpolated Color object',
+ 'example': 'mixed = red.lerp(blue, 0.5) # 50% between red and blue'
+ }
+ },
+
+ # Vector methods
+ 'Vector': {
+ 'magnitude': {
+ 'signature': 'magnitude()',
+ 'description': 'Calculate the length/magnitude of this vector.',
+ 'returns': 'float: The magnitude of the vector',
+ 'example': 'length = vector.magnitude()'
+ },
+ 'magnitude_squared': {
+ 'signature': 'magnitude_squared()',
+ 'description': 'Calculate the squared magnitude of this vector.',
+ 'returns': 'float: The squared magnitude (faster than magnitude())',
+ 'note': 'Use this for comparisons to avoid expensive square root calculation.'
+ },
+ 'normalize': {
+ 'signature': 'normalize()',
+ 'description': 'Return a unit vector in the same direction.',
+ 'returns': 'Vector: New normalized vector with magnitude 1.0',
+ 'raises': 'ValueError: If vector has zero magnitude'
+ },
+ 'dot': {
+ 'signature': 'dot(other)',
+ 'description': 'Calculate the dot product with another vector.',
+ 'args': [('other', 'Vector', 'The other vector')],
+ 'returns': 'float: Dot product of the two vectors'
+ },
+ 'distance_to': {
+ 'signature': 'distance_to(other)',
+ 'description': 'Calculate the distance to another vector.',
+ 'args': [('other', 'Vector', 'The other vector')],
+ 'returns': 'float: Distance between the two vectors'
+ },
+ 'angle': {
+ 'signature': 'angle()',
+ 'description': 'Get the angle of this vector in radians.',
+ 'returns': 'float: Angle in radians from positive x-axis'
+ },
+ 'copy': {
+ 'signature': 'copy()',
+ 'description': 'Create a copy of this vector.',
+ 'returns': 'Vector: New Vector object with same x and y values'
+ }
+ },
+
+ # Scene methods
+ 'Scene': {
+ 'activate': {
+ 'signature': 'activate()',
+ 'description': 'Make this scene the active scene.',
+ 'note': 'Equivalent to calling setScene() with this scene\'s name.'
+ },
+ 'get_ui': {
+ 'signature': 'get_ui()',
+ 'description': 'Get the UI element collection for this scene.',
+ 'returns': 'UICollection: Collection of all UI elements in this scene'
+ },
+ 'keypress': {
+ 'signature': 'keypress(handler)',
+ 'description': 'Register a keyboard handler function for this scene.',
+ 'args': [('handler', 'callable', 'Function that takes (key_name: str, is_pressed: bool)')],
+ 'note': 'Alternative to overriding the on_keypress method.'
+ },
+ 'register_keyboard': {
+ 'signature': 'register_keyboard(callable)',
+ 'description': 'Register a keyboard event handler function for the scene.',
+ 'args': [('callable', 'callable', 'Function that takes (key: str, action: str) parameters')],
+ 'note': 'Alternative to overriding the on_keypress method when subclassing Scene objects.',
+ 'example': '''def handle_keyboard(key, action):
+ print(f"Key '{key}' was {action}")
+ if key == "q" and action == "press":
+ # Handle quit
+ pass
+scene.register_keyboard(handle_keyboard)'''
+ }
+ },
+
+ # Timer methods
+ 'Timer': {
+ 'pause': {
+ 'signature': 'pause()',
+ 'description': 'Pause the timer, stopping its callback execution.',
+ 'note': 'Use resume() to continue the timer from where it was paused.'
+ },
+ 'resume': {
+ 'signature': 'resume()',
+ 'description': 'Resume a paused timer.',
+ 'note': 'Has no effect if timer is not paused.'
+ },
+ 'cancel': {
+ 'signature': 'cancel()',
+ 'description': 'Cancel the timer and remove it from the system.',
+ 'note': 'After cancelling, the timer object cannot be reused.'
+ },
+ 'restart': {
+ 'signature': 'restart()',
+ 'description': 'Restart the timer from the beginning.',
+ 'note': 'Resets the timer\'s internal clock to zero.'
+ }
+ },
+
+ # Window methods
+ 'Window': {
+ 'get': {
+ 'signature': 'get()',
+ 'description': 'Get the Window singleton instance.',
+ 'returns': 'Window: The singleton window object',
+ 'note': 'This is a static method that returns the same instance every time.'
+ },
+ 'center': {
+ 'signature': 'center()',
+ 'description': 'Center the window on the screen.',
+ 'note': 'Only works if the window is not fullscreen.'
+ },
+ 'screenshot': {
+ 'signature': 'screenshot(filename)',
+ 'description': 'Take a screenshot and save it to a file.',
+ 'args': [('filename', 'str', 'Path where to save the screenshot')],
+ 'note': 'Supports PNG, JPG, and BMP formats based on file extension.'
+ }
+ }
+ }
+
+def get_complete_function_documentation():
+ """Return complete documentation for ALL module functions."""
+ return {
+ # Scene Management
+ 'createScene': {
+ 'signature': 'createScene(name: str) -> None',
+ 'description': 'Create a new empty scene with the given name.',
+ 'args': [('name', 'str', 'Unique name for the new scene')],
+ 'raises': 'ValueError: If a scene with this name already exists',
+ 'note': 'The scene is created but not made active. Use setScene() to switch to it.',
+ 'example': 'mcrfpy.createScene("game_over")'
+ },
+ 'setScene': {
+ 'signature': 'setScene(scene: str, transition: str = None, duration: float = 0.0) -> None',
+ 'description': 'Switch to a different scene with optional transition effect.',
+ 'args': [
+ ('scene', 'str', 'Name of the scene to switch to'),
+ ('transition', 'str', 'Transition type: "fade", "slide_left", "slide_right", "slide_up", "slide_down"'),
+ ('duration', 'float', 'Transition duration in seconds (default: 0.0 for instant)')
+ ],
+ 'raises': 'KeyError: If the scene doesn\'t exist',
+ 'example': 'mcrfpy.setScene("game", "fade", 0.5)'
+ },
+ 'currentScene': {
+ 'signature': 'currentScene() -> str',
+ 'description': 'Get the name of the currently active scene.',
+ 'returns': 'str: Name of the current scene',
+ 'example': 'scene_name = mcrfpy.currentScene()'
+ },
+ 'sceneUI': {
+ 'signature': 'sceneUI(scene: str = None) -> UICollection',
+ 'description': 'Get all UI elements for a scene.',
+ 'args': [('scene', 'str', 'Scene name. If None, uses current scene')],
+ 'returns': 'UICollection: All UI elements in the scene',
+ 'raises': 'KeyError: If the specified scene doesn\'t exist',
+ 'example': 'ui_elements = mcrfpy.sceneUI("game")'
+ },
+ 'keypressScene': {
+ 'signature': 'keypressScene(handler: callable) -> None',
+ 'description': 'Set the keyboard event handler for the current scene.',
+ 'args': [('handler', 'callable', 'Function that receives (key_name: str, is_pressed: bool)')],
+ 'example': '''def on_key(key, pressed):
+ if key == "SPACE" and pressed:
+ player.jump()
+mcrfpy.keypressScene(on_key)'''
+ },
+
+ # Audio Functions
+ 'createSoundBuffer': {
+ 'signature': 'createSoundBuffer(filename: str) -> int',
+ 'description': 'Load a sound effect from a file and return its buffer ID.',
+ 'args': [('filename', 'str', 'Path to the sound file (WAV, OGG, FLAC)')],
+ 'returns': 'int: Buffer ID for use with playSound()',
+ 'raises': 'RuntimeError: If the file cannot be loaded',
+ 'example': 'jump_sound = mcrfpy.createSoundBuffer("assets/jump.wav")'
+ },
+ 'loadMusic': {
+ 'signature': 'loadMusic(filename: str, loop: bool = True) -> None',
+ 'description': 'Load and immediately play background music from a file.',
+ 'args': [
+ ('filename', 'str', 'Path to the music file (WAV, OGG, FLAC)'),
+ ('loop', 'bool', 'Whether to loop the music (default: True)')
+ ],
+ 'note': 'Only one music track can play at a time. Loading new music stops the current track.',
+ 'example': 'mcrfpy.loadMusic("assets/background.ogg", True)'
+ },
+ 'playSound': {
+ 'signature': 'playSound(buffer_id: int) -> None',
+ 'description': 'Play a sound effect using a previously loaded buffer.',
+ 'args': [('buffer_id', 'int', 'Sound buffer ID returned by createSoundBuffer()')],
+ 'raises': 'RuntimeError: If the buffer ID is invalid',
+ 'example': 'mcrfpy.playSound(jump_sound)'
+ },
+ 'getMusicVolume': {
+ 'signature': 'getMusicVolume() -> int',
+ 'description': 'Get the current music volume level.',
+ 'returns': 'int: Current volume (0-100)',
+ 'example': 'current_volume = mcrfpy.getMusicVolume()'
+ },
+ 'getSoundVolume': {
+ 'signature': 'getSoundVolume() -> int',
+ 'description': 'Get the current sound effects volume level.',
+ 'returns': 'int: Current volume (0-100)',
+ 'example': 'current_volume = mcrfpy.getSoundVolume()'
+ },
+ 'setMusicVolume': {
+ 'signature': 'setMusicVolume(volume: int) -> None',
+ 'description': 'Set the global music volume.',
+ 'args': [('volume', 'int', 'Volume level from 0 (silent) to 100 (full volume)')],
+ 'example': 'mcrfpy.setMusicVolume(50) # Set to 50% volume'
+ },
+ 'setSoundVolume': {
+ 'signature': 'setSoundVolume(volume: int) -> None',
+ 'description': 'Set the global sound effects volume.',
+ 'args': [('volume', 'int', 'Volume level from 0 (silent) to 100 (full volume)')],
+ 'example': 'mcrfpy.setSoundVolume(75) # Set to 75% volume'
+ },
+
+ # UI Utilities
+ 'find': {
+ 'signature': 'find(name: str, scene: str = None) -> UIDrawable | None',
+ 'description': 'Find the first UI element with the specified name.',
+ 'args': [
+ ('name', 'str', 'Exact name to search for'),
+ ('scene', 'str', 'Scene to search in (default: current scene)')
+ ],
+ 'returns': 'UIDrawable or None: The found element, or None if not found',
+ 'note': 'Searches scene UI elements and entities within grids.',
+ 'example': 'button = mcrfpy.find("start_button")'
+ },
+ 'findAll': {
+ 'signature': 'findAll(pattern: str, scene: str = None) -> list',
+ 'description': 'Find all UI elements matching a name pattern.',
+ 'args': [
+ ('pattern', 'str', 'Name pattern with optional wildcards (* matches any characters)'),
+ ('scene', 'str', 'Scene to search in (default: current scene)')
+ ],
+ 'returns': 'list: All matching UI elements and entities',
+ 'example': 'enemies = mcrfpy.findAll("enemy_*")'
+ },
+
+ # System Functions
+ 'exit': {
+ 'signature': 'exit() -> None',
+ 'description': 'Cleanly shut down the game engine and exit the application.',
+ 'note': 'This immediately closes the window and terminates the program.',
+ 'example': 'mcrfpy.exit()'
+ },
+ 'getMetrics': {
+ 'signature': 'getMetrics() -> dict',
+ 'description': 'Get current performance metrics.',
+ 'returns': '''dict: Performance data with keys:
+- frame_time: Last frame duration in seconds
+- avg_frame_time: Average frame time
+- fps: Frames per second
+- draw_calls: Number of draw calls
+- ui_elements: Total UI element count
+- visible_elements: Visible element count
+- current_frame: Frame counter
+- runtime: Total runtime in seconds''',
+ 'example': 'metrics = mcrfpy.getMetrics()'
+ },
+ 'setTimer': {
+ 'signature': 'setTimer(name: str, handler: callable, interval: int) -> None',
+ 'description': 'Create or update a recurring timer.',
+ 'args': [
+ ('name', 'str', 'Unique identifier for the timer'),
+ ('handler', 'callable', 'Function called with (runtime: float) parameter'),
+ ('interval', 'int', 'Time between calls in milliseconds')
+ ],
+ 'note': 'If a timer with this name exists, it will be replaced.',
+ 'example': '''def update_score(runtime):
+ score += 1
+mcrfpy.setTimer("score_update", update_score, 1000)'''
+ },
+ 'delTimer': {
+ 'signature': 'delTimer(name: str) -> None',
+ 'description': 'Stop and remove a timer.',
+ 'args': [('name', 'str', 'Timer identifier to remove')],
+ 'note': 'No error is raised if the timer doesn\'t exist.',
+ 'example': 'mcrfpy.delTimer("score_update")'
+ },
+ 'setScale': {
+ 'signature': 'setScale(multiplier: float) -> None',
+ 'description': 'Scale the game window size.',
+ 'args': [('multiplier', 'float', 'Scale factor (e.g., 2.0 for double size)')],
+ 'note': 'The internal resolution remains 1024x768, but the window is scaled.',
+ 'example': 'mcrfpy.setScale(2.0) # Double the window size'
+ }
+ }
+
+def get_complete_property_documentation():
+ """Return complete documentation for ALL properties."""
+ return {
+ 'Animation': {
+ 'property': 'str: Name of the property being animated (e.g., "x", "y", "scale")',
+ 'duration': 'float: Total duration of the animation in seconds',
+ 'elapsed_time': 'float: Time elapsed since animation started (read-only)',
+ 'current_value': 'float: Current interpolated value of the animation (read-only)',
+ 'is_running': 'bool: True if animation is currently running (read-only)',
+ 'is_finished': 'bool: True if animation has completed (read-only)'
+ },
+ 'GridPoint': {
+ 'x': 'int: Grid x coordinate of this point',
+ 'y': 'int: Grid y coordinate of this point',
+ 'texture_index': 'int: Index of the texture/sprite to display at this point',
+ 'solid': 'bool: Whether this point blocks movement',
+ 'transparent': 'bool: Whether this point allows light/vision through',
+ 'color': 'Color: Color tint applied to the texture at this point'
+ },
+ 'GridPointState': {
+ 'visible': 'bool: Whether this point is currently visible to the player',
+ 'discovered': 'bool: Whether this point has been discovered/explored',
+ 'custom_flags': 'int: Bitfield for custom game-specific flags'
+ }
+ }
+
+def generate_complete_html_documentation():
+ """Generate complete HTML documentation with NO missing methods."""
+
+ # Get all documentation data
+ method_docs = get_complete_method_documentation()
+ function_docs = get_complete_function_documentation()
+ property_docs = get_complete_property_documentation()
+
+ html_parts = []
+
+ # HTML header with enhanced styling
+ html_parts.append('''
+
+
+
+
+ McRogueFace API Reference - Complete Documentation
+
+
+
+
+''')
+
+ # Title and overview
+ html_parts.append('
McRogueFace API Reference - Complete Documentation
')
+ html_parts.append(f'
Generated on {datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")}
')
+
+ # Table of contents
+ html_parts.append('
')
+ html_parts.append('
Table of Contents
')
+ html_parts.append('
')
+ html_parts.append('
')
+
+ # Functions section
+ html_parts.append('
Functions
')
+
+ # Group functions by category
+ categories = {
+ 'Scene Management': ['createScene', 'setScene', 'currentScene', 'sceneUI', 'keypressScene'],
+ 'Audio': ['createSoundBuffer', 'loadMusic', 'playSound', 'getMusicVolume', 'getSoundVolume', 'setMusicVolume', 'setSoundVolume'],
+ 'UI Utilities': ['find', 'findAll'],
+ 'System': ['exit', 'getMetrics', 'setTimer', 'delTimer', 'setScale']
+ }
+
+ for category, functions in categories.items():
+ html_parts.append(f'
{category}
')
+ for func_name in functions:
+ if func_name in function_docs:
+ html_parts.append(format_function_html(func_name, function_docs[func_name]))
+
+ # Classes section
+ html_parts.append('
Classes
')
+
+ # Get all classes from mcrfpy
+ classes = []
+ for name in sorted(dir(mcrfpy)):
+ if not name.startswith('_'):
+ obj = getattr(mcrfpy, name)
+ if isinstance(obj, type):
+ classes.append((name, obj))
+
+ # Generate class documentation
+ for class_name, cls in classes:
+ html_parts.append(format_class_html_complete(class_name, cls, method_docs, property_docs))
+
+ # Automation section
+ if hasattr(mcrfpy, 'automation'):
+ html_parts.append('
Automation Module
')
+ html_parts.append('
The mcrfpy.automation module provides testing and automation capabilities.
')
+
+ automation = mcrfpy.automation
+ for name in sorted(dir(automation)):
+ if not name.startswith('_'):
+ obj = getattr(automation, name)
+ if callable(obj):
+ html_parts.append(f'
')
+ html_parts.append(f'
automation.{name}
')
+ if obj.__doc__:
+ doc_parts = obj.__doc__.split(' - ')
+ if len(doc_parts) > 1:
+ html_parts.append(f'
{escape_html(doc_parts[1])}
')
+ else:
+ html_parts.append(f'
{escape_html(obj.__doc__)}
')
+ html_parts.append('
')
+
+ html_parts.append('
')
+ html_parts.append(f'
{func_doc["signature"]}
')
+ html_parts.append(f'
{escape_html(func_doc["description"])}
')
+
+ # Arguments
+ if 'args' in func_doc:
+ html_parts.append('
')
+ html_parts.append('
Arguments:
')
+ for arg in func_doc['args']:
+ html_parts.append('
')
+ html_parts.append(f'{arg[0]} ')
+ html_parts.append(f'({arg[1]}): ')
+ html_parts.append(f'{escape_html(arg[2])}')
+ html_parts.append('
')
+ html_parts.append('
')
+
+ # Returns
+ if 'returns' in func_doc:
+ html_parts.append('
')
+ html_parts.append(f'Returns: {escape_html(func_doc["returns"])}')
+ html_parts.append('
')
+
+ # Raises
+ if 'raises' in func_doc:
+ html_parts.append('
')
+ html_parts.append(f'Raises: {escape_html(func_doc["raises"])}')
+ html_parts.append('
')
+
+ # Note
+ if 'note' in func_doc:
+ html_parts.append('
')
+ html_parts.append(f'Note: {escape_html(func_doc["note"])}')
+ html_parts.append('
')
+
+ # Example
+ if 'example' in func_doc:
+ html_parts.append('
')
+ html_parts.append('
Example:
')
+ html_parts.append('
')
+ html_parts.append(escape_html(func_doc['example']))
+ html_parts.append('
')
+ html_parts.append('
')
+
+ html_parts.append('
')
+ html_parts.append(f'
{class_name}
')
+
+ # Class description
+ if cls.__doc__:
+ html_parts.append(f'
{escape_html(cls.__doc__)}
')
+
+ # Properties
+ if class_name in property_docs:
+ html_parts.append('
Properties:
')
+ for prop_name, prop_desc in property_docs[class_name].items():
+ html_parts.append(f'
')
+ html_parts.append(f'{prop_name}: {escape_html(prop_desc)}')
+ html_parts.append('
')
+
+ # Methods
+ methods_to_document = []
+
+ # Add inherited methods for UI classes
+ if any(base.__name__ == 'Drawable' for base in cls.__bases__ if hasattr(base, '__name__')):
+ methods_to_document.extend(['get_bounds', 'move', 'resize'])
+
+ # Add class-specific methods
+ if class_name in method_docs:
+ methods_to_document.extend(method_docs[class_name].keys())
+
+ # Add methods from introspection
+ for attr_name in dir(cls):
+ if not attr_name.startswith('_') and callable(getattr(cls, attr_name)):
+ if attr_name not in methods_to_document:
+ methods_to_document.append(attr_name)
+
+ if methods_to_document:
+ html_parts.append('
Methods:
')
+ for method_name in set(methods_to_document):
+ # Get method documentation
+ method_doc = None
+ if class_name in method_docs and method_name in method_docs[class_name]:
+ method_doc = method_docs[class_name][method_name]
+ elif method_name in method_docs.get('Drawable', {}):
+ method_doc = method_docs['Drawable'][method_name]
+
+ if method_doc:
+ html_parts.append(format_method_html(method_name, method_doc))
+ else:
+ # Basic method with no documentation
+ html_parts.append(f'
')
+ html_parts.append(f'{method_name}(...)')
+ html_parts.append('
')
+
+ html_parts.append('
')
+ html_parts.append(f'
{method_doc["signature"]}
')
+ html_parts.append(f'
{escape_html(method_doc["description"])}
')
+
+ # Arguments
+ if 'args' in method_doc:
+ for arg in method_doc['args']:
+ html_parts.append(f'
')
+ html_parts.append(f'{arg[0]} ')
+ html_parts.append(f'({arg[1]}): ')
+ html_parts.append(f'{escape_html(arg[2])}')
+ html_parts.append('
')
+
+ # Returns
+ if 'returns' in method_doc:
+ html_parts.append(f'
')
+ html_parts.append(f'Returns: {escape_html(method_doc["returns"])}')
+ html_parts.append('
')
+
+ # Note
+ if 'note' in method_doc:
+ html_parts.append(f'
')
+ html_parts.append(f'Note: {escape_html(method_doc["note"])}')
+ html_parts.append('
')
+
+ # Example
+ if 'example' in method_doc:
+ html_parts.append(f'
')
+ html_parts.append('
Example:')
+ html_parts.append('
')
+ html_parts.append(escape_html(method_doc['example']))
+ html_parts.append('
')
+ html_parts.append('
')
+
+ html_parts.append('
See also: {text_escaped}
'
-
- elif format == 'web':
- # Link to hosted docs and escape for safe HTML
- web_path = ref.replace('docs/', '').replace('.md', '')
- href = html.escape(f"{base_url}/{web_path}", quote=True)
- text_escaped = html.escape(text)
- return f'See also: {text_escaped}
'
-
- elif format == 'markdown':
- # Markdown link
- return f'\n**See also:** [{text}]({ref})'
-
- else: # 'python' or default
- # Keep as plain text for Python docstrings
- return match.group(0)
-
- # For HTML formats, escape the entire docstring first, then process links
- if format in ('html', 'web'):
- # Split by the link pattern, escape non-link parts, then reassemble
- parts = []
- last_end = 0
-
- for match in re.finditer(link_pattern, docstring):
- # Escape the text before this match
- if match.start() > last_end:
- parts.append(html.escape(docstring[last_end:match.start()]))
-
- # Process the link (replace_link handles escaping internally)
- parts.append(replace_link(match))
- last_end = match.end()
-
- # Escape any remaining text after the last match
- if last_end < len(docstring):
- parts.append(html.escape(docstring[last_end:]))
-
- return ''.join(parts)
- else:
- # For non-HTML formats, just do simple replacement
- return re.sub(link_pattern, replace_link, docstring)
-
# Must be run with McRogueFace as interpreter
try:
import mcrfpy
@@ -365,10 +304,8 @@ def generate_html_docs():
html_content += f"""
{func_name}{parsed['signature'] if parsed['signature'] else '(...)'}
+
{html.escape(parsed['description'])}
"""
- if parsed['description']:
- description = transform_doc_links(parsed['description'], format='html')
- html_content += f"
{description}
\n"
if parsed['args']:
html_content += "
Arguments:
\n
\n"
@@ -424,10 +361,9 @@ def generate_html_docs():
{method_name}{parsed['signature'] if parsed['signature'] else '(...)'}
"""
-
+
if parsed['description']:
- description = transform_doc_links(parsed['description'], format='html')
- html_content += f"
{description}
\n"
+ html_content += f"
{html.escape(parsed['description'])}
\n"
if parsed['args']:
html_content += "
\n"
@@ -493,10 +429,9 @@ def generate_markdown_docs():
parsed = func_info["parsed"]
md_content += f"### `{func_name}{parsed['signature'] if parsed['signature'] else '(...)'}`\n\n"
-
+
if parsed['description']:
- description = transform_doc_links(parsed['description'], format='markdown')
- md_content += f"{description}\n\n"
+ md_content += f"{parsed['description']}\n\n"
if parsed['args']:
md_content += "**Arguments:**\n"
@@ -544,10 +479,9 @@ def generate_markdown_docs():
parsed = method_info['parsed']
md_content += f"#### `{method_name}{parsed['signature'] if parsed['signature'] else '(...)'}`\n\n"
-
+
if parsed['description']:
- description = transform_doc_links(parsed['description'], format='markdown')
- md_content += f"{description}\n\n"
+ md_content += f"{parsed['description']}\n\n"
if parsed['args']:
md_content += "**Arguments:**\n"
diff --git a/tools/test_link_transform.py b/tools/test_link_transform.py
deleted file mode 100644
index 37e3b05..0000000
--- a/tools/test_link_transform.py
+++ /dev/null
@@ -1,55 +0,0 @@
-#!/usr/bin/env python3
-"""Test script for link transformation function."""
-
-import re
-
-def transform_doc_links(docstring, format='html', base_url=''):
- """Transform MCRF_LINK patterns based on output format.
-
- Detects pattern: "See also: TEXT (docs/path.md)"
- Transforms to appropriate format for output type.
- """
- if not docstring:
- return docstring
-
- link_pattern = r'See also: ([^(]+) \(([^)]+)\)'
-
- def replace_link(match):
- text, ref = match.group(1).strip(), match.group(2).strip()
-
- if format == 'html':
- # Convert docs/foo.md → foo.html
- href = ref.replace('docs/', '').replace('.md', '.html')
- return f'
See also: {text}
'
-
- elif format == 'web':
- # Link to hosted docs
- web_path = ref.replace('docs/', '').replace('.md', '')
- return f'
See also: {text}
'
-
- elif format == 'markdown':
- # Markdown link
- return f'\n**See also:** [{text}]({ref})'
-
- else: # 'python' or default
- # Keep as plain text for Python docstrings
- return match.group(0)
-
- return re.sub(link_pattern, replace_link, docstring)
-
-# Test cases
-test_doc = "Description text.\n\nSee also: Tutorial Guide (docs/guide.md)\n\nMore text."
-
-html_result = transform_doc_links(test_doc, format='html')
-print("HTML:", html_result)
-assert '
Tutorial Guide' in html_result
-
-md_result = transform_doc_links(test_doc, format='markdown')
-print("Markdown:", md_result)
-assert '[Tutorial Guide](docs/guide.md)' in md_result
-
-plain_result = transform_doc_links(test_doc, format='python')
-print("Python:", plain_result)
-assert 'See also: Tutorial Guide (docs/guide.md)' in plain_result
-
-print("\nSUCCESS: All transformations work correctly")
diff --git a/tools/test_vector_docs.py b/tools/test_vector_docs.py
deleted file mode 100644
index bf07e47..0000000
--- a/tools/test_vector_docs.py
+++ /dev/null
@@ -1,39 +0,0 @@
-import mcrfpy
-import sys
-
-# Check Vector.magnitude docstring
-mag_doc = mcrfpy.Vector.magnitude.__doc__
-print("magnitude doc:", mag_doc)
-assert "magnitude()" in mag_doc
-assert "Calculate the length/magnitude" in mag_doc
-assert "Returns:" in mag_doc
-
-# Check Vector.dot docstring
-dot_doc = mcrfpy.Vector.dot.__doc__
-print("dot doc:", dot_doc)
-assert "dot(other: Vector)" in dot_doc
-assert "Args:" in dot_doc
-assert "other:" in dot_doc
-
-# Check Vector.normalize docstring
-normalize_doc = mcrfpy.Vector.normalize.__doc__
-print("normalize doc:", normalize_doc)
-assert "normalize()" in normalize_doc
-assert "Return a unit vector" in normalize_doc
-assert "Returns:" in normalize_doc
-assert "Note:" in normalize_doc
-
-# Check Vector.x property docstring
-x_doc = mcrfpy.Vector.x.__doc__
-print("x property doc:", x_doc)
-assert "X coordinate of the vector" in x_doc
-assert "float" in x_doc
-
-# Check Vector.y property docstring
-y_doc = mcrfpy.Vector.y.__doc__
-print("y property doc:", y_doc)
-assert "Y coordinate of the vector" in y_doc
-assert "float" in y_doc
-
-print("SUCCESS: All docstrings present and complete")
-sys.exit(0)