# docgen

**Repository Path**: princekind/docgen

## Basic Information

- **Project Name**: docgen
- **Description**: 基于源代码来生成架构设计文档和详细设计文档
- **Primary Language**: C++
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-05-18
- **Last Updated**: 2026-05-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# docgen

A C/C++ documentation generator that produces architecture and detailed design documents in Markdown, with PlantUML diagrams, by parsing source code through libclang.

## Requirements

### Build Dependencies

Required to compile the docgen tool:

- **C++17 compiler** (gcc 7+, clang 5+, or MSVC 2017+)
- **CMake** 3.8+
- **LLVM + Clang** with libclang development headers

### Document Conversion Dependencies

Required to convert Markdown output to DOCX/HTML and render PlantUML diagrams:

- **Pandoc** 2.0+ — converts Markdown to DOCX/HTML
- **Python 3** — runs the PlantUML rendering filter
- **Python `plantuml` package** — remote PlantUML rendering (via plantuml.com)

Optional for local (offline) PlantUML rendering:

- **Java** runtime (JRE) + **plantuml.jar**, or
- **PlantUML CLI** package from system package manager

## Installing Dependencies

### Ubuntu / Debian

```bash
# Build dependencies
sudo apt install build-essential cmake libclang-dev

# Document conversion
sudo apt install pandoc python3 python3-pip
pip3 install plantuml

# Optional: local PlantUML rendering (native)
sudo apt install plantuml        # Option A: CLI from apt
# or
sudo apt install default-jre     # Option B: Java + manually download
wget https://github.com/plantuml/plantuml/releases/latest/download/plantuml.jar
sudo mv plantuml.jar /usr/share/plantuml/
```

### Fedora / RHEL

```bash
# Build dependencies
sudo dnf install gcc-c++ cmake clang-devel

# Document conversion
sudo dnf install pandoc python3 python3-pip
pip3 install plantuml

# Optional: local PlantUML rendering
sudo dnf install plantuml        # Option A: CLI from dnf
# or
sudo dnf install java-11-openjdk # Option B: Java + JAR
wget https://github.com/plantuml/plantuml/releases/latest/download/plantuml.jar
sudo mv plantuml.jar /usr/share/plantuml/
```

### macOS (Homebrew)

```bash
# Build dependencies
brew install llvm cmake

# Document conversion
brew install pandoc python
pip3 install plantuml

# Optional: local PlantUML rendering
brew install plantuml             # CLI from Homebrew
```

### Windows (vcpkg)

```bash
# Build dependencies
vcpkg install llvm cmake

# Document conversion
choco install pandoc python3
pip3 install plantuml
```

### Verify Installation

```bash
# Build toolchain
cmake --version
clang++ --version

# Document conversion
pandoc --version | head -1
python3 -c "import plantuml; print('plantuml', plantuml.__version__)"
```

## Build

```bash
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j4
```

## Usage

```
docgen <compile_commands_dir> [options]

Arguments:
  compile_commands_dir   Path to directory containing compile_commands.json

Options:
  -o, --output <dir>        Output directory (default: doc)
  -p, --project <name>        Project name (default: from compile_commands_dir parent)
  -i, --ignore-dir <dir>    Exclude directory by basename (repeatable)
  -f, --ignore-file <name>  Exclude source file by basename (repeatable)
  -h, --help                Show help and exit
  --version                 Show version and exit
```

### Example

```bash
./docgen ~/nlog/build -o ~/nlog/docs -p NLog -i test -i 3rdparty
```

## Output

### Architecture Design Document

A single `Architecture_Design.md` with the following sections:

- Cover page and revision history
- Architecture component diagram (PlantUML)
- Software unit list with source files
- External interfaces table
- Data types (class diagram + table)
- Global variables and macro definitions
- Software decomposition (per-unit component diagrams + internal interfaces)
- Dynamic behavior (sequence diagrams for each external interface)

### Detailed Design Documents

One `Detailed_Design_<unit>.md` per software unit, containing:

- Function descriptions and data structures (class diagrams + field tables)
- Variables, parameters, macros, and external function tables
- Static behavior (block/class diagram)
- Dynamic behavior (per-function sequence diagrams)
- Function design tables with per-parameter input/output classification and activity diagrams

## Comment Format

The parser extracts documentation from doxygen-style comments. Supported tags: `@brief`, `@asil`, `@requirement`/`@req`, `@param[in|out|in,out]`, `@return`, `@def`, and `@file`.

```
/**
 * @brief Computes CRC32 checksum over a memory buffer.
 * @param[in]  data  Pointer to input data buffer.
 * @param[in]  len   Length of input data in bytes.
 * @param[out] crc   Output CRC32 value.
 * @return 0 on success, -1 on error.
 * @asil ASIL_B
 * @requirement SWRS-1001
 */
int crc32(const uint8_t* data, size_t len, uint32_t* crc);
```

Single-line `///` and `/*! */` comments are also supported. See [`required_comments.md`](required_comments.md) for the full specification. Use [`ai_comment_prompt.md`](ai_comment_prompt.md) as an AI prompt to generate docgen-compatible comments.

## Pipeline

1. **CompileCommandsParser** — loads `compile_commands.json`
2. **ASTParser** — parses each translation unit with libclang, builds IR (`ProjectModel`)
   - Phase 1: parses `.c`/`.cpp` files with compile context, collects project header declarations
   - Phase 2: parses standalone headers not already covered by Phase 1
3. **ArchDocGenerator** — generates the architecture design document
4. **DetailDocGenerator** — generates per-unit detailed design documents

File paths in output documents are rendered relative to the parent of `compile_commands_dir`.

## Document Conversion

Generated Markdown documents can be converted to DOCX or HTML:

```bash
# Batch convert all .md files in the output directory
scripts/docgen_convert.sh <output_dir> [options]
  -f, --format <fmt>     Output format: docx or html (default: docx)
  -t, --template <file>  Word template for styles
  --verbose              Show detailed progress

# Convert a single file
scripts/md2word.sh -i <file.md> -o <output> -f docx [-t <template>]
```

A Word template (`scripts/template.docx`) with pre-configured heading styles and multi-level numbering is included.

## Project Structure

| File | Purpose |
|---|---|
| `src/main.cpp` | Entry point and orchestration |
| `include/ir.h` | Intermediate representation data structures |
| `src/compile_commands_parser.cpp` `include/compile_commands_parser.h` | Parses `compile_commands.json` |
| `src/ast_parser.cpp` `include/ast_parser.h` | libclang-based C/C++ AST parser |
| `src/plantuml_generator.cpp` `include/plantuml_generator.h` | PlantUML diagram generation |
| `src/markdown_generator.cpp` `include/markdown_generator.h` | Markdown formatting utilities |
| `src/arch_doc_generator.cpp` `include/arch_doc_generator.h` | Architecture design document writer |
| `src/detail_doc_generator.cpp` `include/detail_doc_generator.h` | Detailed design document writer |
| `scripts/md2word.sh` | Single-file Markdown to DOCX/HTML converter |
| `scripts/docgen_convert.sh` | Batch converter for all .md in output dir |
| `scripts/plantuml_api_filter.py` | Pandoc filter for PlantUML rendering (native or remote) |
| `scripts/template.docx` | Word template with styles and numbering |
| `required_comments.md` | Comment format specification for docgen |
| `ai_comment_prompt.md` | AI prompt for generating docgen-compatible comments |