4.4.1. Markdown generator

• Output structure
  • Fields section
  • Relations section
  • Named Rows section
• CI/CD usage
  • Example output
    • Table page structure
  • Generator script
  • Source code

This script is used to generate database documentation in Markdown format from the OrmFactory XML schema export. It produces one Markdown file per table and a global index file for navigation across the database structure.

The generator is designed to keep documentation always synchronized with the current model state. Since the source is the schema export, any structural change in the model (tables, columns, relations, named rows) is immediately reflected in the generated documentation during CI/CD execution.

Output structure

For each table, the generator creates a separate Markdown file containing:

• Table metadata (name, class, description)
• Fields (columns with types, nullability and comments)
• Relations (foreign keys)
• Named Rows (static reference data extracted from live database)

In addition, an index.md file is generated to provide navigation between all tables.

Fields section

Each table is rendered as a structured field list:

• Field name (model property)
• Column name (database column)
• Data type (resolved from database type)
• Nullability
• Description (from column comments)

This structure allows the documentation to be used both as a technical reference and as a lightweight data dictionary.

Relations section

Foreign keys are rendered as explicit navigation links between entities:

• Source field in current table
• Target entity (class)
• Source column used for relation

This section turns the documentation into a navigable graph of the database schema.

Named Rows section

Named Rows represent domain-level reference data stored in the database. Unlike enums, they are not static code constructs but live database records that are explicitly marked as significant for generation.

Each NamedRow entry is rendered as a Markdown table:

• Dynamic column detection from XML attributes
• Aggregation of all row fields into a single unified table
• Stable ordering of columns based on first occurrence

This allows the generator to document business-critical reference data such as roles, statuses, or configuration entities.

CI/CD usage

The generator is intended to run in a Docker-based CI/CD pipeline after schema changes:

1. Merge request modifies database model
2. OrmFactory generates updated XML schema
3. Documentation generator processes XML
4. Markdown files are regenerated
5. Updated documentation is committed or published

This ensures documentation is always consistent with the actual database state.

Example output

Table page structure

# UserRole

Powers and permissions for system users

**Database table:** `UserRoles`
**Model class:** `UserRole`

## Fields
...
## Relations
...
## Named Rows
...

Generator script

At the beginning of the script there is a configuration section that defines output behavior and naming rules:

INDENT = "\t"
NEWLINE = "\n"
OUTPUT_DIR = "C:/5/docs"

The script reads the XML schema from standard input and generates a full documentation set:

• one Markdown file per table
• a global index file with links to all tables

Source code

Direct link to download the script: md-docs.py or view online.