How Wiki Generation Creates Markdown from Community Structure in code-review-graph

The wiki generator transforms detected code communities into navigable markdown documentation by assembling structured metadata, member tables, and dependency graphs into individual pages with a central index.

The code-review_graph repository provides an automated documentation pipeline that converts internal graph-based community structures into human-readable markdown wikis. At the core of this pipeline, the wiki generation system orchestrates data from community detection algorithms to produce structured documentation that maps architectural boundaries and execution flows. Understanding this process reveals how the tool bridges static analysis outputs with maintainable architecture documentation.

The Wiki Generation Pipeline

The entry point generate_wiki in code_review_graph/wiki.py orchestrates a six-stage workflow that converts raw graph data into a structured wiki. Each community detected in the codebase receives its own markdown page with standardized sections, while a top-level index provides navigation.

Step 1: Query Community Metadata

The process begins by calling 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 member qualified names. This data structure serves as the foundation for all subsequent markdown generation.

Step 2: Normalize Community Names

Before writing files, the private helper _slugify converts community names into URL-safe filenames. This function transforms text to lower-case ASCII, substitutes hyphens for whitespace, truncates results to 80 characters, and appends numeric suffixes when collisions occur. This deterministic naming ensures consistent file paths across regeneration cycles.

Step 3: Assemble Page Content

The _generate_community_page function constructs each markdown page by concatenating four distinct sections into a single string using "\n".join(lines).

Header and Overview Section

The generator creates an H1 title derived from the community name, followed by metadata badges displaying:

• Total member count
• Cohesion score
• Dominant programming language
• Optional description when available

This information populates the introductory block at lines 32-44 and 55-66 of wiki.py.

Members Table

The system queries the GraphStore to list up to the first 50 non-file members, displaying:

• Kind (class, function, variable)
• File path location
• Line range within the source file

If a community contains no eligible members, the generator gracefully renders an empty state rather than failing.

Execution Flows

For dynamic analysis, the generator retrieves the top 10 execution flows passing through community members, showing:

• Flow name
• Criticality score
• Call depth

This section includes defensive error handling that falls back to a SQLite error message if the flow table is missing from the database, as implemented in lines 100-125.

Cross-Community Dependencies

Using store.get_outgoing_targets and store.get_incoming_sources, the generator counts edges crossing community boundaries and displays:

• Top 15 outgoing dependency targets
• Top 15 incoming dependency sources

This reveals architectural coupling between modules, implemented in lines 130-165.

Step 4: Write Individual Pages

The generate_wiki function iterates over each community, generates a unique slug, and writes content to <wiki_dir>/<slug>.md. It tracks file status (new, updated, or unchanged) by comparing content hashes before writing, avoiding unnecessary filesystem operations when data has not changed.

Step 5: Generate the Index

After processing all communities, the generator creates index.md containing:

• A header with total community count
• An alphabetically sorted table mapping community names to their markdown files

This provides the entry point for navigating the generated documentation.

Step 6: Return Generation Summary

Finally, generate_wiki returns a dictionary reporting:

• pages_generated: Newly created files
• pages_updated: Modified existing files
• pages_unchanged: Files skipped due to identical content

Running the Generator

To generate the wiki from your analyzed codebase:

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 invokes get_communities internally, then delegates to _generate_community_page for each entry before writing to disk and building the index.

Key Source Files

The wiki generation system spans three primary modules:

• code_review_graph/wiki.py: Contains generate_wiki, _generate_community_page, and _slugify, implementing the core markdown assembly and file I/O logic.

• code_review_graph/communities.py: Provides get_communities which supplies the structural metadata and member lists consumed by the wiki generator.

• code_review_graph/graph.py: Defines GraphStore, the database façade that supplies node details, execution flows, and cross-community dependency edges to the documentation pipeline.

Summary

• The wiki generator queries community data via get_communities in communities.py to obtain structural metadata and member lists.
• _slugify creates safe filenames by normalizing community names to 80-character ASCII slugs with collision detection.
• _generate_community_page assembles four content sections: overview metadata, member tables, execution flows, and dependency analysis.
• Individual pages are written to <slug>.md files with change detection, while index.md provides alphabetical navigation.
• The system returns a detailed summary dict tracking generation, update, and unchanged counts for auditability.

Frequently Asked Questions

How does the generator handle duplicate community names?

When _slugify produces a filename that already exists in the output directory, the generator appends a numeric suffix (e.g., auth-service-1.md) to ensure uniqueness. This collision handling occurs during the file writing loop in generate_wiki at lines 11-40 of wiki.py.

What happens when execution flow data is missing?

If the SQLite database lacks the flow table or the query fails, the execution flows section displays an error message rather than crashing the generation process. This defensive programming ensures the wiki remains usable even with incomplete static analysis data.

How many members appear in each community page?

The members table displays up to the first 50 non-file members per community. File nodes are filtered out to focus on callable and definable entities such as classes and functions, keeping tables readable while remaining comprehensive.

Can I force regeneration of existing wiki pages?

Yes. Pass force=True to generate_wiki to bypass the content hash comparison and rewrite every markdown file regardless of whether the underlying community data has changed. This is useful when updating templates or fixing generation bugs.

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