john
/
McRogueFace
1
0
Fork 0
Code Issues 48 Pull Requests Projects 1 Releases Wiki Activity

Create automated API documentation extraction tool #97

New Issue
Closed
opened 2025-07-05 19:08:52 +00:00 by john · 1 comment
john commented 2025-07-05 19:08:52 +00:00
Owner
Copy Link

Build a tool to extract Python API documentation from C++ source code and generate formatted API reference documentation.
Affects: Documentation infrastructure
Depends on: Create inline C++ documentation system

Build a tool to extract Python API documentation from C++ source code and generate formatted API reference documentation. Affects: Documentation infrastructure Depends on: Create inline C++ documentation system
john added the
Documentation
Major Feature
Demo Target
 labels 2025-07-05 19:08:52 +00:00
john added the
Refactoring & Cleanup
system:python-binding
workflow:blocked
 labels 2025-10-26 00:44:42 +00:00
john added the
priority:tier1-active
system:documentation
workflow:needs-documentation
 labels 2025-10-26 00:49:14 +00:00
john commented 2025-10-30 19:45:56 +00:00
Author
Owner
Copy Link

Implementation Complete ✅

The automated API documentation extraction tool is now fully operational.

What Was Delivered

Enhanced Documentation Extraction:

  • tools/generate_dynamic_docs.py enhanced with link transformation support
  • Supports multiple output formats: HTML, Markdown, Python docstrings
  • Link transformation converts MCRF_LINK references based on output format:
    • HTML: <a href="guide.html">Tutorial</a>
    • Web: <a href="https://docs.mcrogueface.com/guide">Tutorial</a>
    • Markdown: [Tutorial](docs/guide.md)
    • Python: See also: Tutorial (docs/guide.md)

Documentation Pipeline:

  1. C++ source with MCRF_* macros → compile
  2. Introspection via Python's dir(), getattr(), __doc__
  3. Transformation: MCRF_LINK patterns detected and converted
  4. Output: docs/api_reference_dynamic.html and docs/API_REFERENCE_DYNAMIC.md

HTML Escaping:

  • Properly escapes user-provided descriptions to prevent HTML injection
  • Link HTML preserved while escaping surrounding text

Verification:

  • Vector class: Complete documentation with 0 "..." placeholders
  • All UI classes: Enhanced property documentation visible
  • Generated docs successfully include transformed links

Dependencies Resolved

✅ Issue #92 (inline C++ documentation system) - COMPLETED

  • The macro system provides the structured documentation that this tool extracts

Integration with Existing Tools

  • Works alongside tools/generate_stubs.py (type stub generation)
  • Replaces 5 obsolete documentation scripts that were deleted
  • Single command regenerates all documentation: ./build/mcrogueface --headless --exec tools/generate_dynamic_docs.py

Future Enhancements

Optional (not required for completion):

  • PDF generation from source (parse C++ directly without compiling)
  • Man page generation with proper formatting
  • Link validation CI (ensure MCRF_LINK targets exist)
  • Auto-generate "Related Methods" sections from link analysis

The core functionality is complete and proven working across Vector, Drawable, and all UI classes.

## Implementation Complete ✅ The automated API documentation extraction tool is now fully operational. ### What Was Delivered **Enhanced Documentation Extraction:** - `tools/generate_dynamic_docs.py` enhanced with link transformation support - Supports multiple output formats: HTML, Markdown, Python docstrings - Link transformation converts MCRF_LINK references based on output format: - HTML: `<a href="guide.html">Tutorial</a>` - Web: `<a href="https://docs.mcrogueface.com/guide">Tutorial</a>` - Markdown: `[Tutorial](docs/guide.md)` - Python: `See also: Tutorial (docs/guide.md)` **Documentation Pipeline:** 1. C++ source with MCRF_* macros → compile 2. Introspection via Python's `dir()`, `getattr()`, `__doc__` 3. Transformation: MCRF_LINK patterns detected and converted 4. Output: `docs/api_reference_dynamic.html` and `docs/API_REFERENCE_DYNAMIC.md` **HTML Escaping:** - Properly escapes user-provided descriptions to prevent HTML injection - Link HTML preserved while escaping surrounding text **Verification:** - Vector class: Complete documentation with 0 "..." placeholders - All UI classes: Enhanced property documentation visible - Generated docs successfully include transformed links ### Dependencies Resolved ✅ Issue #92 (inline C++ documentation system) - **COMPLETED** - The macro system provides the structured documentation that this tool extracts ### Integration with Existing Tools - Works alongside `tools/generate_stubs.py` (type stub generation) - Replaces 5 obsolete documentation scripts that were deleted - Single command regenerates all documentation: `./build/mcrogueface --headless --exec tools/generate_dynamic_docs.py` ### Future Enhancements **Optional (not required for completion):** - PDF generation from source (parse C++ directly without compiling) - Man page generation with proper formatting - Link validation CI (ensure MCRF_LINK targets exist) - Auto-generate "Related Methods" sections from link analysis The core functionality is complete and proven working across Vector, Drawable, and all UI classes.
john closed this issue 2025-10-30 19:46:03 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
master
rogueliketutorial25
alpha_presentable
alpha_streamline_2
alpha_streamline_1
interpreter_mode
grid_entity_integration
reprs_and_member_names
break_up_ui_h
standardize_font_handling
standardize_vector_handling
standardize_color_handling
standardize_texture_handling
raii_pyobjects
rebase-for-7DRL_Feb-2024
engjam_uicollection
engjam_ui_overhaul
Labels
Clear labels   
Alpha Release Requirement

This issue is a blocker to 0.1 Alpha release of McRogueFace.

  
Bugfix

   
Demo Target

Functionality to demonstrate; Depends on new features, but this issue isn't for writing them.

  
Documentation

   
Major Feature

Significant time and effort required.

  
Minor Feature

Some effort required to create or overhaul functionality.

  
priority:tier1-active

Current development focus - critical path to v1.0

  
priority:tier2-foundation

Important foundation work - not blocking v1.0

  
priority:tier3-future

Future features - deferred until after v1.0

  
Refactoring & Cleanup

no new functionality, just improving the codebase.

  
system:animation

Animation and property interpolation

  
system:documentation

Documentation infrastructure

  
system:grid

Grid system and spatial containers

  
system:input

Input handling and events

  
system:performance

Performance optimization and profiling

  
system:python-binding

Python/C++ binding layer

  
system:rendering

Rendering pipeline and visuals

  
system:ui-hierarchy

UI component hierarchy and composition

  
Tiny Feature

quick and easy - a few lines or with little interconnection around the codebase

  
workflow:blocked

Blocked by other work - waiting on dependencies

  
workflow:needs-benchmark

Needs performance testing and benchmarks

  
workflow:needs-documentation

Needs documentation before or after implementation

No Label
Alpha Release Requirement
Bugfix
Demo Target
Documentation
Major Feature
Minor Feature
priority:tier1-active
priority:tier2-foundation
priority:tier3-future
Refactoring & Cleanup
system:animation
system:documentation
system:grid
system:input
system:performance
system:python-binding
system:rendering
system:ui-hierarchy
Tiny Feature
workflow:blocked
workflow:needs-benchmark
workflow:needs-documentation
Milestone
Clear milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
No Assignees
1 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: john/McRogueFace#97
No description provided.
Delete Branch "%!s(<nil>)"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?