Skip to main content

Documentation Consolidation System

This document describes the automated documentation consolidation system that creates a single DOCX file containing all documentation from the /readme/ folder.

Overview​

The KAI platform includes an automated system that consolidates all Markdown documentation files into a single Microsoft Word (DOCX) document. This makes it easier to share comprehensive documentation with stakeholders who prefer traditional document formats over browsing multiple Markdown files.

How It Works​

The system uses a GitHub Action workflow that:

  1. Runs automatically after each deployment to the main branch
  2. Runs on a weekly schedule (Monday at 00:00 UTC)
  3. Can be triggered manually via GitHub Actions interface

The workflow performs the following steps:

  1. Checks out the repository code
  2. Sets up Python environment
  3. Installs required dependencies (python-docx, markdown, beautifulsoup4)
  4. Creates and executes a Python script that:
    • Scans the /readme/ directory for all Markdown (.md) files
    • Converts each Markdown file to HTML and then to DOCX format
    • Combines all content into a single DOCX document with proper formatting
    • Adds a title page, table of contents, and processing summary
    • Saves the consolidated document as /readme/readme.docx
  5. Commits and pushes the generated DOCX file back to the repository

Generated Document Structure​

The consolidated DOCX document includes:

  • Title Page: Contains the title "KAI Platform Documentation" and generation timestamp
  • Table of Contents: Automatically generated when opened in Microsoft Word
  • Content Sections: Each Markdown file is converted to a section with:
    • Section title (derived from filename)
    • Source file reference
    • Original content with preserved formatting (headings, lists, code blocks, etc.)
  • Processing Summary: Statistics about the number of files processed

Formatting Details​

The conversion process handles various Markdown elements:

  • Headings: Converted to Word headings with appropriate levels
  • Lists: Converted to bulleted or numbered lists
  • Code blocks: Formatted with Courier New font
  • Tables: Converted to text representation
  • Text formatting: Basic formatting (bold, italic) is preserved

Usage​

Accessing the Consolidated Documentation​

The consolidated documentation is available in two ways:

  1. In the repository: The file is located at /readme/readme.docx and is automatically updated after each deployment to the main branch or on the weekly schedule.

  2. As a GitHub Actions artifact: Each time the workflow runs, the documentation is also uploaded as an artifact named "kai-documentation" that can be downloaded directly from the GitHub Actions interface. These artifacts are retained for 90 days.

Manual Triggering​

To manually trigger the documentation generation:

  1. Go to the GitHub repository
  2. Navigate to Actions → Generate Consolidated Documentation
  3. Click "Run workflow"
  4. Select the branch (usually main)
  5. Click "Run workflow"

Troubleshooting​

If the documentation generation fails or produces unexpected results:

  1. Check the GitHub Actions logs for error messages
  2. Verify that all Markdown files in the /readme/ directory are properly formatted
  3. Ensure that the required dependencies are available and up-to-date

Future Improvements​

Potential future enhancements to the documentation consolidation system:

  • Support for more complex Markdown elements (nested tables, advanced formatting)
  • PDF generation in addition to DOCX
  • Custom styling options
  • Automatic distribution of generated documentation to stakeholders
  • Integration with the existing monitoring dashboard