feat(docs): add XML and Markdown documentation generation

Add comprehensive documentation tooling with Doxygen XML output and
custom Markdown converter for API reference generation.

Changes:
- Configure Doxygen for XML primary output with schema validation
- Add xml-to-markdown.py converter with proper parameter parsing
- Generate single-file API reference with table-formatted parameters
- Add docs:markdown task for Markdown generation
- Update docs:package to include Markdown in distribution
- Document XML format structure and integration patterns
- Disable broken SQL-specific features, add workarounds

The system extracts 84 documented functions with @param, @return, @note
tags into clean Markdown with professional parameter tables.

Note: Doxygen SQL parsing is imperfect (treats SQL as C++), but
documentation comments are extracted correctly. Function signatures
may show incorrect types but descriptions are accurate.

Author: tobyhede

.github/workflows/release-eql.yml

@@ -94,6 +94,7 @@ jobs:
       - name: Generate documentation
         run: |
           mise run docs:generate
+          mise run docs:markdown
 
       - name: Package documentation
         run: |

CLAUDE.md

@@ -12,8 +12,17 @@ This project uses `mise` for task management. Common commands:
 - `mise run postgres:down` - Stop PostgreSQL containers
 - `mise run reset` - Reset database state
 - `mise run clean` (alias: `mise r k`) - Clean release files
+
+### Documentation
 - `mise run docs:generate` - Generate API documentation (requires doxygen)
+  - Outputs XML (primary) and HTML (preview) formats
+  - XML suitable for downstream processing/website integration
+  - See `docs/api/README.md` for XML format details
+- `mise run docs:markdown` - Convert XML to Markdown API reference
+  - Generates single-file API reference: `docs/api/markdown/API.md`
+  - Includes 84 documented functions with parameters, return values, and source links
 - `mise run docs:validate` - Validate documentation coverage and tags
+- `mise run docs:package` - Package XML docs for distribution (~230KB archive)
 
 ### Testing
 - Run all tests: `mise run test`
@@ -138,6 +147,18 @@ mise run docs:validate:documented-sql # Validate SQL syntax (requires database)
 
 Template files (e.g., `version.template`) must be documented. The Doxygen comments are automatically included in generated files during build.
 
+### Generated Documentation Format
+
+The documentation is generated in **XML format** as the primary output:
+
+- **Location**: `docs/api/xml/`
+- **Format**: Doxygen XML (v1.15.0) with XSD schemas
+- **Usage**: Machine-readable, suitable for downstream processing
+- **Publishing**: Package with `mise run docs:package` → creates `eql-docs-xml-2.x.tar.gz`
+- **Integration**: See `docs/api/README.md` for XML structure and transformation examples
+
+HTML output is also generated in `docs/api/html/` for local preview only.
+
 ## Development Notes
 
 - SQL files are modular - put operator wrappers in `operators.sql`, implementation in `functions.sql`

Doxyfile

@@ -15,16 +15,31 @@ CREATE_SUBDIRS         = NO
 #---------------------------------------------------------------------------
 # Build Settings
 #---------------------------------------------------------------------------
+# PRIMARY OUTPUT: XML for downstream processing
+# HTML: Optional, for local preview only
+# MARKDOWN: Experimental (may not generate in all Doxygen versions)
 
 GENERATE_HTML          = YES
 GENERATE_LATEX         = NO
-GENERATE_XML           = NO
+GENERATE_XML           = YES
 GENERATE_MAN           = NO
+GENERATE_MARKDOWN      = YES
 
 HTML_OUTPUT            = html
 HTML_FILE_EXTENSION    = .html
 HTML_DYNAMIC_SECTIONS  = YES
 
+# XML Settings - Primary documentation format
+XML_OUTPUT             = xml
+XML_PROGRAMLISTING     = YES
+
+# Markdown generation not supported in Doxygen 1.15.0
+# Use external tools to convert XML to Markdown:
+# - doxybook2 (C++, recommended): https://github.com/matusnovak/doxybook2
+# - moxygen (Node.js): https://github.com/sourcey/moxygen
+# - esp-doxybook (Python): https://pypi.org/project/esp-doxybook/
+# See docs/api/README.md for integration examples
+
 #---------------------------------------------------------------------------
 # Input Settings
 #---------------------------------------------------------------------------
@@ -35,13 +50,18 @@ RECURSIVE              = YES
 EXCLUDE_PATTERNS       = *_test.sql
 
 # Treat SQL files as C++ for parsing
+# NOTE: Doxygen has no native SQL support. Parsing as C++ is imperfect but allows
+# extraction of function names and documentation comments.
 EXTENSION_MAPPING      = sql=C++ template=C++
 
 # CRITICAL: Input filter to convert SQL comments (--!) to C++ style (//!)
 # This is REQUIRED for Doxygen to recognize SQL comments
 INPUT_FILTER           = "tasks/docs/doxygen-filter.sh"
 FILTER_SOURCE_FILES    = YES
 
+# Source patterns - treat SQL keywords more gracefully
+FILTER_PATTERNS        =
+
 #---------------------------------------------------------------------------
 # Extraction Settings
 #---------------------------------------------------------------------------
@@ -63,6 +83,16 @@ SHOW_NAMESPACES        = YES
 JAVADOC_AUTOBRIEF      = YES
 OPTIMIZE_OUTPUT_FOR_C  = YES
 
+# Disable some C++-specific features that don't apply to SQL
+BUILTIN_STL_SUPPORT    = NO
+CPP_CLI_SUPPORT        = NO
+IDL_PROPERTY_SUPPORT   = NO
+
+# Enable better handling of functions/procedures
+EXTRACT_LOCAL_METHODS  = YES
+SORT_MEMBER_DOCS       = YES
+SORT_BRIEF_DOCS        = YES
+
 #---------------------------------------------------------------------------
 # Warning Settings
 #---------------------------------------------------------------------------