Preserve user code during HTML file regeneration

Current Issue

Currently, the software completely regenerates HTML files on each execution, which overwrites all manual modifications made by the user.

Proposed Enhancement

Implement a user code preservation tag system, similar to the one used by STMicroelectronics in their code generation tools (STM32CubeMX, STM32CubeIDE).

Desired Behavior

The generator should recognize and preserve content between special tags:

<!-- USER CODE BEGIN section_name -->

<!-- USER CODE END section_name -->

During HTML file regeneration:

The software reads the existing HTML file
It extracts and preserves all content between USER CODE BEGIN and USER CODE END tags
It regenerates the HTML file with new content
It reinjects user code at the appropriate locations

Benefits

✅ Allows users to customize generated HTML files
✅ Prevents loss of modifications during regeneration
✅ Proven system familiar to STM32 tools users
✅ Maintains traceability between generated and user code

Implementation Phases

Phase 1: Predefined Tags

In the first implementation, the application will generate a predefined set of USER CODE sections in the HTML files:

custom_styles - For additional CSS styles
custom_description - For custom descriptions and notes
additional_examples - For usage examples
footer - For custom footer content

These sections will be automatically included in all generated HTML files with empty content by default.

Phase 2: Dynamic Tag Detection

In a second phase, the application should automatically detect and preserve any USER CODE tags that users may have added themselves, even if they are not part of the predefined set. This provides maximum flexibility for users to add custom sections anywhere they need without being limited to predefined locations.

Example:

<!-- Auto-generated content -->

<!-- USER CODE BEGIN my_custom_section -->
<div>User added this section manually</div>
<!-- USER CODE END my_custom_section -->

<!-- More auto-generated content -->

The application should scan for all USER CODE BEGIN/END pairs in existing files and preserve them regardless of their section name.

Usage Example

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>MyFunctionBlock - Documentation</title>
    <style type="text/css">
        /* Auto-generated styles */
        .fubLayout { border-collapse: collapse; }
        .fubGradBlue { background: linear-gradient(#4472C4, #2E5396); }
        /* ... other generated styles ... */
    </style>
    <!-- USER CODE BEGIN custom_styles -->
    <style>
        /* Custom user styles */
        .highlight { background-color: yellow; }
        .important { color: red; font-weight: bold; }
    </style>
    <!-- USER CODE END custom_styles -->
</head>
<body>
    <h1>MyFunctionBlock</h1>
    
    <!-- USER CODE BEGIN custom_description -->
    <div class="user-notes">
        <h2>Implementation Notes</h2>
        <p>This function block handles motor control with safety features...</p>
        <ul>
            <li>Maximum speed: 3000 RPM</li>
            <li>Safety timeout: 500ms</li>
        </ul>
    </div>
    <!-- USER CODE END custom_description -->
    
    <!-- Auto-generated function block diagram -->
    <table id="fub" cellspacing="0" class="fubLayout">
        <tr>
            <th class="fubDataTypeIn"></th>
            <th colspan="2" class="fubGradBlue">MyFunctionBlock</th>
            <th class="fubDataTypeOut"></th>
        </tr>
        <tr>
            <td class="fubDataTypeIn">
                <table class="fubData">
                    <tr>
                        <td class="fubElementRight">BOOL</td>
                        <td width="10"><hr width="20px" size="1" color="#000000"></td>
                    </tr>
                </table>
            </td>
            <td class="fubGradOrange1">
                <table class="fubIn">
                    <tr><td class="fubElementLeft">Enable</td></tr>
                </table>
            </td>
            <td class="fubGradOrange2">
                <table class="fubOut">
                    <tr><td class="fubElementRight">Status</td></tr>
                </table>
            </td>
            <td class="fubDataTypeOut">
                <table class="fubData">
                    <tr>
                        <td width="10"><hr width="20px" size="1" color="#000000"></td>
                        <td class="fubElementLeft">DINT</td>
                    </tr>
                </table>
            </td>
        </tr>
    </table>
    
    <!-- USER CODE BEGIN additional_examples -->
    <h2>Usage Examples</h2>
    <pre><code>
(* Example usage in Structured Text *)
fbMotor(Enable := TRUE);
IF fbMotor.Status = 0 THEN
    (* Motor running normally *)
END_IF;
    </code></pre>
    <!-- USER CODE END additional_examples -->
    
    <!-- USER CODE BEGIN footer -->
    <footer>
        <p>Last modified by: John Doe - 2026-01-08</p>
    </footer>
    <!-- USER CODE END footer -->
</body>
</html>

Suggested Implementation

The htmlGenerator.py file should be modified to:

Add a function to parse USER CODE tags with regex pattern matching
Store user content before regeneration in a dictionary (section_name → content)
Generate HTML with predefined empty USER CODE sections
Reinject preserved content at the correct locations after generation
(Phase 2) Scan for any USER CODE tags not in predefined list and preserve them

Description

Current Issue

Proposed Enhancement

Desired Behavior

Benefits

Implementation Phases

Phase 1: Predefined Tags

Phase 2: Dynamic Tag Detection

Usage Example

Suggested Implementation

Contributor guide

First steps

Assessment

Preserve user code during HTML file regeneration

Description

Current Issue

Proposed Enhancement

Desired Behavior

Benefits

Implementation Phases

Phase 1: Predefined Tags

Phase 2: Dynamic Tag Detection

Usage Example

Suggested Implementation

Contributor guide

First steps

Assessment

Get new issues in your inbox