How the Wiki Generator Creates Markdown from Communities in Code-Review-Graph

The wiki generator in code_review_graph/wiki.py transforms detected code communities into structured markdown documentation by fetching community metadata, slugifying names into safe filenames, generating detailed pages with member tables and cross-community dependencies, and compiling an alphabetical index.

The tirth8205/code-review-graph repository analyzes codebases as graph structures to detect architectural communities. Understanding how the wiki generator creates markdown from these communities reveals how the tool automatically produces navigable documentation of software architecture.

Step 1: Fetching Community Metadata

The process begins by retrieving structured community data. The generator calls get_communities(store) from code_review_graph/communities.py, which returns a list of dictionaries containing each community's name, size, cohesion, dominant language, description, and the qualified names of its members.

This data collection happens at communities.py#L60-L73, providing the raw material that will be formatted into human-readable documentation.

Step 2: Normalizing Filenames with Slugification

Before writing files, the generator converts community names into URL-safe filenames using the private helper _slugify (defined at wiki.py#L24-L30). This function:

• Converts text to lowercase ASCII
• Replaces spaces and special characters with hyphens
• Truncates results to a maximum of 80 characters

This ensures that community names like "Authentication Service" become authentication-service.md, preventing filesystem errors while maintaining readability.

Step 3: Assembling Community Page Content

The core formatting logic resides in _generate_community_page(store, community) at wiki.py#L32-L71. This function constructs each page by concatenating several distinct markdown sections into a single string.

Header and Overview Section

The generator creates a level-1 heading (#) with the community name, followed by metadata badges showing size, cohesion score, and dominant programming language. If available, the community description appears as introductory text. This assembly occurs between wiki.py#L32-L44 and wiki.py#L55-L66.

Member Documentation Table

The members section lists up to the first 50 non-file members, displaying each member's kind (function, class, etc.), file path, and line range. The code at wiki.py#L67-L92 handles empty results gracefully, ensuring the table renders correctly even for sparse communities.

Execution Flow Analysis

For dynamic behavior documentation, the generator retrieves the top 10 execution flows passing through community members (implemented at wiki.py#L100-L125). Each flow entry includes the flow name, criticality score, and depth level. The implementation includes error handling for missing SQLite flow tables, allowing generation to continue even when flow data is unavailable.

Cross-Community Dependencies

The dependencies section (lines wiki.py#L130-L165) analyzes architectural coupling by counting outgoing and incoming cross-community edges using store.get_outgoing_targets() and store.get_incoming_sources(). It documents the 15 most common external targets and sources, revealing which other communities interact with the current one and how frequently.

Step 4: Writing Files and Managing Collisions

Within the main generate_wiki function (wiki.py#L11-L40), the generator iterates over every community and derives a unique slug for each. If slug collisions occur (communities with identical names), the system appends a numeric suffix to ensure unique filenames. The function writes each processed community to <wiki_dir>/<slug>.md and tracks whether the file was newly created, updated, or unchanged based on content comparison.

Step 5: Compiling the Index Page

After processing individual communities, the generator creates an index.md file (lines wiki.py#L41-L57) that serves as the wiki homepage. This index includes a header, total community count, and a markdown table linking each community slug to its documentation file. The table rows sort alphabetically by community name to ensure consistent, predictable navigation.

Step 6: Reporting Generation Statistics

The generate_wiki function concludes by returning a summary dictionary at wiki.py#L73-L77. This report contains:

• pages_generated: Count of newly created files
• pages_updated: Count of modified existing files
• pages_unchanged: Count of files requiring no updates

This feedback allows automation pipelines to track documentation drift and regeneration requirements.

Implementation Example

The following example demonstrates how to invoke the wiki generator against an existing graph store:

from pathlib import Path
from code_review_graph.graph import GraphStore
from code_review_graph.wiki import generate_wiki

# Assume `store` is an already-populated GraphStore instance.

wiki_dir = Path("./code-wiki")

# Generate the markdown wiki (force regeneration if you want to refresh every file)

summary = generate_wiki(store, wiki_dir, force=False)

print("Wiki generation summary:")
print(f"  Pages generated: {summary['pages_generated']}")
print(f"  Pages updated:   {summary['pages_updated']}")
print(f"  Pages unchanged: {summary['pages_unchanged']}")

This script fetches communities via get_communities, processes each through _generate_community_page, writes individual markdown files to the specified directory, and creates the master index.md file.

Summary

• The wiki generator resides in code_review_graph/wiki.py and orchestrates documentation creation through the generate_wiki function.
• Community data originates from get_communities in code_review_graph/communities.py, providing architectural metadata and member lists.
• The _slugify helper ensures safe filenames by converting names to lowercase ASCII with hyphens and an 80-character limit.
• Each community page includes an overview header, a members table (max 50 entries), execution flows (top 10), and dependency analysis (top 15 cross-community connections).
• The generator handles filename collisions, writes individual pages, compiles an alphabetically-sorted index, and returns statistics about the operation.

Frequently Asked Questions

What file contains the core wiki generation logic?

The primary implementation lives in code_review_graph/wiki.py. This module contains generate_wiki for orchestration, _generate_community_page for content assembly, and _slugify for filename normalization.

How does the generator handle special characters in community names?

The _slugify function at wiki.py#L24-L30 converts community names to safe filenames by lowercasing, replacing spaces and special characters with hyphens, and truncating to 80 characters. This prevents filesystem errors while maintaining human-readable URLs.

What happens if the execution flow database table is missing?

The execution flow section (wiki.py#L100-L125) includes exception handling for SQLite errors. If the flow table is absent, the generator catches the error and continues processing, ensuring the wiki generates successfully even without dynamic flow data.

How many community members appear in each generated page?

The members table displays up to the first 50 non-file members per community. This limit balances comprehensive documentation with file size and readability, as implemented in the member listing logic at wiki.py#L67-L92.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}