doc-toolkit

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# Documentation Toolkit

[![CI](https://github.com/YOUR_USERNAME/doc-toolkit/workflows/CI/badge.svg)](https://github.com/YOUR_USERNAME/doc-toolkit/actions/workflows/ci.yml)
[![Release](https://github.com/YOUR_USERNAME/doc-toolkit/workflows/Release/badge.svg)](https://github.com/YOUR_USERNAME/doc-toolkit/actions/workflows/release.yml)
[![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
[![.NET](https://img.shields.io/badge/.NET-9.0-purple.svg)](https://dotnet.microsoft.com/)
[![SemVer](https://img.shields.io/badge/semver-2.0.0-green.svg)](https://semver.org/)

This toolkit provides a complete, reusable documentation framework for all projects.  
It centralizes rules, templates, scripts, and automation so you never duplicate work.

# Core Purpose

A project scaffolding and publishing tool for creating documentation projects following [docs-as-code](https://www.writethedocs.org/guide/docs-as-code/) principles from [Write the Docs](https://www.writethedocs.org/guide/).

Like `dotnet new` or Yeoman, but for documentation projects. 

1. **Initialize**: `doc init MyProject` - Creates complete project structure with folders, configs, Git repo
2. **Generate**: `doc generate prd "Name"` - Creates documents from templates
3. **Publish**: `doc publish web` - Compiles and packages documentation for deployment (web, PDF, CHM)
4. **Deploy**: Published output ready for Azure, AWS, Docker, GitHub Pages

Source repository stays private. Published output is public-ready.

Use this toolkit to generate:
- PRDs  
- RFPs  
- Tenders  
- SOWs  
- Architecture Docs  
- Solution Proposals  
- Engineering Specs  
- API Designs  
- Data Models  
- Blog Entries  
- Weekly Logs  

And to initialize new project workspaces with:
- A consistent folder structure  
- Git repository  
- Cursor IDE configuration  

---

## 📁 Toolkit Structure

```
/doc-toolkit/
    /src/
        /DocToolkit/          # C# CLI Application
            /Accessors/        # Storage volatility (Accessors)
            /Engines/          # Algorithm volatility (Engines)
            /Managers/         # Workflow volatility (Managers)
            /ifx/              # Infrastructure folder
                /Commands/     # CLI command implementations (Clients)
                /Events/       # Event definitions
                /Infrastructure/ # DI, Event Bus, etc.
                /Interfaces/   # All interfaces
                /Models/       # Data models
                Program.cs      # Application entry point
            DocToolkit.csproj

    /templates/               # Document templates (embedded as resources in build)
        prd.md
        rfp.md
        tender.md
        architecture.md
        solution.md
        sow.md
        sla.md
        spec.md
        api.md
        data.md
        blog.md
        weekly-log.md

    /scripts/                 # PowerShell/Python scripts (legacy)
        generate-doc.cmd
        generate-doc.ps1
        init-project.cmd
        init-project.ps1
        summarize-source.ps1
        semantic-index.ps1
        semantic-search.ps1
        build_kg.py
        build-knowledge-graph.ps1

    /.cursor/                 # Cursor IDE configuration
        /rules/
        cursor.json

    README.md
    requirements.txt
```

---

## 🚀 Core Capabilities

### CLI Application (Recommended)

The toolkit now includes a beautiful C# CLI application built with [Spectre.Console](https://spectreconsole.net/) for a modern, cross-platform experience, plus a self-hosted web interface for viewing and sharing documents.

#### Installation

Build the CLI application:
```bash
cd src/DocToolkit
dotnet build
```

Or run directly:
```bash
cd src/DocToolkit
dotnet run -- <command>
```

#### Commands

**1. Initialize a new project:**
```bash
doc init MyProject
```

**2. Generate a document:**
```bash
doc generate prd "User Management"
doc gen sow "Cloud Migration"  # Short alias
doc gen prd "API Design" --subfolder "architecture"  # Organize in subfolder
```

**3. Validate setup:**
```bash
doc validate
```

**4. Start web server to view and share documents:**
```bash
doc web
doc web --port 8080
doc web --host 0.0.0.0 --port 5000  # Accessible from network
doc web --docs-dir ./my-docs  # Custom docs directory
```

**5. Publish documentation for deployment:**
```bash
doc publish                    # Publish web interface
doc publish --format web       # Web interface (default)
doc publish --format all       # All formats (web, pdf, chm, single)
doc publish --target azure     # With Azure deployment config
doc publish --target docker    # With Docker configuration
```

#### Publishing System

The toolkit includes a comprehensive publishing system that:

- **Compiles documentation** into multiple formats (web, PDF, CHM, single-file)
- **Packages web interface** for static deployment (no server required)
- **Generates deployment configs** for Azure, AWS, Docker, GitHub Pages
- **Separates source from output** - keep repository private, publish output publicly

#### Docs-as-Code Philosophy

The toolkit follows [docs-as-code](https://www.doctave.com/docs-as-code) principles:

- **Version Control**: Git repository initialized automatically
- **Markdown-Based**: All templates in Markdown format
- **Automated Quality**: GitHub Actions workflows for quality checks
- **CI/CD Ready**: Automated linting and deployment workflows
- **Style Guides**: Microsoft Style Guide support (optional)
- **Collaboration**: PR-based workflow with automated checks
- **Workflow**: Edit → Review (PR) → Automated Checks → Publish

See [docs/DOCS-AS-CODE-ALIGNMENT.md](https://github.com/jsolarz/doc-toolkit/blob/HEAD/docs/DOCS-AS-CODE-ALIGNMENT.md) for complete alignment with industry best practices.

#### Web Interface

The web interface provides a beautiful, self-contained document viewer that allows you to:

- **Browse Documents**: View all generated documents in a sidebar list
- **View Content**: Click any document to view its full content with markdown rendering
- **Share with Team**: Access the web interface from any device on your network
- **Self-Contained**: All web assets are embedded in the application - no external dependencies
- **Real-time Updates**: Refresh the document list to see newly generated documents

**Features:**
- Modern, responsive design
- Markdown rendering with syntax highlighting
- Document metadata (type, size, last modified)
- Organized by document type
- Mobile-friendly interface

**Access:**
- Default: `http://localhost:5000`
- Network access: Use `--host 0.0.0.0` to allow access from other devices
- Custom port: Use `--port` to specify a different port

### Script-Based Usage (Legacy)

The original PowerShell and Python scripts are still available for advanced use cases.

#### 1. **Project Initialization**
Creates a new project workspace with:
- `/docs/`
- `/source/`
- `/.cursor/` (linked to toolkit rules/templates)
- `.gitignore`
- Git repository + initial commit
- README

**CLI:**
```bash
doc init MyProject
```

**Scripts:**
```powershell
.\scripts\init-project.ps1 MyProject
```

#### 2. **Document Generation**
Generate any document type using templates. Templates are embedded in the application for self-contained deployment.

**CLI:**
```bash
doc generate prd "User Management"
doc gen sow "Cloud Migration"
doc gen prd "API Design" --subfolder "architecture"  # Organize in docs/architecture/
doc gen sow "Project X" --output "./my-docs" --subfolder "sows"  # Custom output with subfolder
```

**Scripts:**
```bash
generate-doc.cmd sow "Cloud Migration"
.\generate-doc.ps1 -Type prd -Name "User Management"
```

---

## 🧠 Why This Toolkit Exists

- Centralizes all documentation rules  
- Ensures consistency across all projects  
- Eliminates duplication  
- Makes onboarding new team members trivial  
- Provides a scalable, professional documentation workflow  

---

## 🛠 Requirements

### CLI Application Requirements
- **.NET 9.0 SDK** or later
- **Poppler** (optional, for advanced PDF features)
- **Tesseract** (optional, for OCR)

### System Requirements (Scripts)
- **PowerShell 5+** (Windows) or **Bash** (Linux/Mac)
- **Python 3.10+**
- **Poppler** (for PDF text extraction)
- **Tesseract** (optional, for OCR)

### Installation

#### Windows
Install external tools via Chocolatey:
```powershell
choco install poppler
choco install tesseract
```

#### Linux (Ubuntu/Debian)
```bash
sudo apt-get update
sudo apt-get install poppler-utils tesseract-ocr
```

#### macOS
```bash
brew install poppler tesseract
```

### NuGet Packages

The CLI application uses the following NuGet packages (automatically restored):
- `Microsoft.Data.Sqlite` - For event persistence
- `Microsoft.Extensions.DependencyInjection` - For dependency injection
- `DocumentFormat.OpenXml` - For DOCX/PPTX text extraction
- `UglyToad.PdfPig` - For PDF text extraction
- `Spectre.Console` - For beautiful CLI interface

**Note**: Python is no longer required! The CLI is fully C# native with dependency injection and event bus.

### Validate Setup

**CLI:**
```bash
doc validate
```

**Scripts:**
```powershell
.\scripts\validate-setup.ps1
```

For automatic fixes (scripts only):
```powershell
.\scripts\validate-setup.ps1 -Fix
```

---

## 🔧 Troubleshooting

### Missing NuGet Packages
**Error**: `Missing required libraries`

**Solution**:
```bash
cd src/DocToolkit
dotnet restore
```

### PDF Text Extraction Fails
**Error**: `Unable to extract PDF text`

**Solution**:
1. Install Poppler: `choco install poppler` (Windows) or `apt-get install poppler-utils` (Linux)
2. Ensure `pdftotext` is in your PATH
3. Verify with: `pdftotext -v`

### Script Execution Policy (PowerShell)
**Error**: Script execution is disabled

**Solution**:
```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

---

---

## 📚 Documentation

### Project Documentation
- **[PRD](https://github.com/jsolarz/doc-toolkit/blob/HEAD/docs/PRD-Documentation-Toolkit.md)** - Product Requirements Document
- **[Architecture](https://github.com/jsolarz/doc-toolkit/blob/HEAD/docs/ARCHITECTURE-Documentation-Toolkit.md)** - Architecture Design Document
- **[Data Model](https://github.com/jsolarz/doc-toolkit/blob/HEAD/docs/DATA-Documentation-Toolkit.md)** - Data Model Document
- **[Engineering Spec](https://github.com/jsolarz/doc-toolkit/blob/HEAD/docs/SPEC-Documentation-Toolkit.md)** - Engineering Specification
- **[Solution Proposal](https://github.com/jsolarz/doc-toolkit/blob/HEAD/docs/SOLUTION-Documentation-Toolkit.md)** - Solution Proposal

### Technical Documentation
- **[Technical Documentation](https://github.com/jsolarz/doc-toolkit/blob/HEAD/docs/TECHNICAL-DOCUMENTATION.md)** - Complete technical reference
- **[System Design](https://github.com/jsolarz/doc-toolkit/blob/HEAD/docs/design.md)** - IDesign Method™ system design
- **[Code Documentation Standards](https://github.com/jsolarz/doc-toolkit/blob/HEAD/docs/CODE-DOCUMENTATION-STANDARDS.md)** - Documentation guidelines
- **[Developer Quick Reference](https://github.com/jsolarz/doc-toolkit/blob/HEAD/docs/DEVELOPER-QUICK-REFERENCE.md)** - Quick reference guide

### Standards & Compliance
- **[IDesign C# Coding Standard Compliance](https://github.com/jsolarz/doc-toolkit/blob/HEAD/docs/IDESIGN-CSHARP-CODING-STANDARD-COMPLIANCE.md)** - Coding standard compliance
- **[IDesign Method™ Guidelines](https://github.com/jsolarz/doc-toolkit/blob/HEAD/.cursor/rules/idesign-method.mdc)** - Architecture guidelines

---

## 📝 Version

Current version: **0.0.1-alpha.1**

This project follows [Semantic Versioning 2.0.0](https://semver.org/). See [CHANGELOG.md](https://github.com/jsolarz/doc-toolkit/blob/HEAD/CHANGELOG.md) for complete version history and all development steps.

---

## 🤝 Contributing

We welcome contributions! Please see [CONTRIBUTING.md](https://github.com/jsolarz/doc-toolkit/blob/HEAD/CONTRIBUTING.md) for guidelines.

---

## 📄 License

This project is licensed under the **GNU Affero General Public License v3.0 (AGPL-3.0)** - see [LICENSE](https://github.com/jsolarz/doc-toolkit/tree/HEAD/LICENSE) for details.

**Why AGPL-3.0?** This license ensures that any modifications or derivative works must also be open source, including when used in network services. This protects the open-source nature of the project while allowing commercial use with the requirement to contribute back improvements.

For alternative licensing options, see [LICENSE-OPTIONS.md](https://github.com/jsolarz/doc-toolkit/blob/HEAD/LICENSE-OPTIONS.md).

---

## 🧩 Extending the Toolkit

You can add:
- New templates (add to `/templates/`)  
- New rulesets (add to `/.cursor/rules/`)  
- New snippets  
- New automation scripts (add to `/scripts/`)  

Just keep everything inside `/doc-toolkit/`.

---

## 🚀 Future Enhancements

The following features are planned for future releases:

### Semantic Intelligence Features

- **Semantic Indexing**: Build vector embeddings from source files for intelligent search
  - `doc index` - Build semantic index from source files
  - Support for multiple embedding models (ONNX-based)
  - Configurable chunking strategies

- **Semantic Search**: Query project knowledge using natural language
  - `doc search "query"` - Search across indexed content
  - Top-K result ranking
  - Similarity-based retrieval

- **Knowledge Graph Generation**: Extract and visualize relationships
  - `doc graph` - Build knowledge graph from source files
  - Entity and topic extraction
  - Relationship mapping
  - Graph visualization (JSON, Graphviz, Markdown)

- **Document Summarization**: Generate context summaries
  - `doc summarize` - Create summaries of source files
  - Extractive and abstractive summarization
  - Context-aware summaries

These features will require:
- ONNX model support (all-MiniLM-L6-v2.onnx or similar)
- Microsoft.ML.OnnxRuntime NuGet package
- Additional processing capabilities for embeddings and graph generation

Documentation Toolkit

This toolkit provides a complete, reusable documentation framework for all projects.
It centralizes rules, templates, scripts, and automation so you never duplicate work.

Core Purpose

A project scaffolding and publishing tool for creating documentation projects following docs-as-code principles from Write the Docs.

Like dotnet new or Yeoman, but for documentation projects.

Initialize: doc init MyProject - Creates complete project structure with folders, configs, Git repo
Generate: doc generate prd "Name" - Creates documents from templates
Publish: doc publish web - Compiles and packages documentation for deployment (web, PDF, CHM)
Deploy: Published output ready for Azure, AWS, Docker, GitHub Pages

Source repository stays private. Published output is public-ready.

Use this toolkit to generate:

PRDs
RFPs
Tenders
SOWs
Architecture Docs
Solution Proposals
Engineering Specs
API Designs
Data Models
Blog Entries
Weekly Logs

And to initialize new project workspaces with:

A consistent folder structure
Git repository
Cursor IDE configuration

📁 Toolkit Structure

/doc-toolkit/
    /src/
        /DocToolkit/          # C# CLI Application
            /Accessors/        # Storage volatility (Accessors)
            /Engines/          # Algorithm volatility (Engines)
            /Managers/         # Workflow volatility (Managers)
            /ifx/              # Infrastructure folder
                /Commands/     # CLI command implementations (Clients)
                /Events/       # Event definitions
                /Infrastructure/ # DI, Event Bus, etc.
                /Interfaces/   # All interfaces
                /Models/       # Data models
                Program.cs      # Application entry point
            DocToolkit.csproj

    /templates/               # Document templates (embedded as resources in build)
        prd.md
        rfp.md
        tender.md
        architecture.md
        solution.md
        sow.md
        sla.md
        spec.md
        api.md
        data.md
        blog.md
        weekly-log.md

    /scripts/                 # PowerShell/Python scripts (legacy)
        generate-doc.cmd
        generate-doc.ps1
        init-project.cmd
        init-project.ps1
        summarize-source.ps1
        semantic-index.ps1
        semantic-search.ps1
        build_kg.py
        build-knowledge-graph.ps1

    /.cursor/                 # Cursor IDE configuration
        /rules/
        cursor.json

    README.md
    requirements.txt

🚀 Core Capabilities

CLI Application (Recommended)

The toolkit now includes a beautiful C# CLI application built with Spectre.Console for a modern, cross-platform experience, plus a self-hosted web interface for viewing and sharing documents.

Installation

Build the CLI application:

cd src/DocToolkit
dotnet build

Or run directly:

cd src/DocToolkit
dotnet run -- <command>

Commands

1. Initialize a new project:

doc init MyProject

2. Generate a document:

doc generate prd "User Management"
doc gen sow "Cloud Migration"  # Short alias
doc gen prd "API Design" --subfolder "architecture"  # Organize in subfolder

3. Validate setup:

doc validate

4. Start web server to view and share documents:

doc web
doc web --port 8080
doc web --host 0.0.0.0 --port 5000  # Accessible from network
doc web --docs-dir ./my-docs  # Custom docs directory

5. Publish documentation for deployment:

doc publish                    # Publish web interface
doc publish --format web       # Web interface (default)
doc publish --format all       # All formats (web, pdf, chm, single)
doc publish --target azure     # With Azure deployment config
doc publish --target docker    # With Docker configuration

Publishing System

The toolkit includes a comprehensive publishing system that:

Compiles documentation into multiple formats (web, PDF, CHM, single-file)
Packages web interface for static deployment (no server required)
Generates deployment configs for Azure, AWS, Docker, GitHub Pages
Separates source from output - keep repository private, publish output publicly

Docs-as-Code Philosophy

The toolkit follows docs-as-code principles:

Version Control: Git repository initialized automatically
Markdown-Based: All templates in Markdown format
Automated Quality: GitHub Actions workflows for quality checks
CI/CD Ready: Automated linting and deployment workflows
Style Guides: Microsoft Style Guide support (optional)
Collaboration: PR-based workflow with automated checks
Workflow: Edit → Review (PR) → Automated Checks → Publish

See docs/DOCS-AS-CODE-ALIGNMENT.md for complete alignment with industry best practices.

Web Interface

The web interface provides a beautiful, self-contained document viewer that allows you to:

Browse Documents: View all generated documents in a sidebar list
View Content: Click any document to view its full content with markdown rendering
Share with Team: Access the web interface from any device on your network
Self-Contained: All web assets are embedded in the application - no external dependencies
Real-time Updates: Refresh the document list to see newly generated documents

Features:

Modern, responsive design
Markdown rendering with syntax highlighting
Document metadata (type, size, last modified)
Organized by document type
Mobile-friendly interface

Access:

Default: http://localhost:5000
Network access: Use --host 0.0.0.0 to allow access from other devices
Custom port: Use --port to specify a different port

Script-Based Usage (Legacy)

The original PowerShell and Python scripts are still available for advanced use cases.

1. Project Initialization

Creates a new project workspace with:

/docs/
/source/
/.cursor/ (linked to toolkit rules/templates)
.gitignore
Git repository + initial commit
README

CLI:

doc init MyProject

Scripts:

.\scripts\init-project.ps1 MyProject

2. Document Generation

Generate any document type using templates. Templates are embedded in the application for self-contained deployment.

CLI:

doc generate prd "User Management"
doc gen sow "Cloud Migration"
doc gen prd "API Design" --subfolder "architecture"  # Organize in docs/architecture/
doc gen sow "Project X" --output "./my-docs" --subfolder "sows"  # Custom output with subfolder

Scripts:

generate-doc.cmd sow "Cloud Migration"
.\generate-doc.ps1 -Type prd -Name "User Management"

🧠 Why This Toolkit Exists

Centralizes all documentation rules
Ensures consistency across all projects
Eliminates duplication
Makes onboarding new team members trivial
Provides a scalable, professional documentation workflow

🛠 Requirements

CLI Application Requirements

.NET 9.0 SDK or later
Poppler (optional, for advanced PDF features)
Tesseract (optional, for OCR)

System Requirements (Scripts)

PowerShell 5+ (Windows) or Bash (Linux/Mac)
Python 3.10+
Poppler (for PDF text extraction)
Tesseract (optional, for OCR)

Installation

Windows

Install external tools via Chocolatey:

choco install poppler
choco install tesseract

Linux (Ubuntu/Debian)

sudo apt-get update
sudo apt-get install poppler-utils tesseract-ocr

macOS

brew install poppler tesseract

NuGet Packages

The CLI application uses the following NuGet packages (automatically restored):

Microsoft.Data.Sqlite - For event persistence
Microsoft.Extensions.DependencyInjection - For dependency injection
DocumentFormat.OpenXml - For DOCX/PPTX text extraction
UglyToad.PdfPig - For PDF text extraction
Spectre.Console - For beautiful CLI interface

Note: Python is no longer required! The CLI is fully C# native with dependency injection and event bus.

Validate Setup

CLI:

doc validate

Scripts:

.\scripts\validate-setup.ps1

For automatic fixes (scripts only):

.\scripts\validate-setup.ps1 -Fix

🔧 Troubleshooting

Missing NuGet Packages

Error: Missing required libraries

Solution:

cd src/DocToolkit
dotnet restore

PDF Text Extraction Fails

Error: Unable to extract PDF text

Solution:

Install Poppler: choco install poppler (Windows) or apt-get install poppler-utils (Linux)
Ensure pdftotext is in your PATH
Verify with: pdftotext -v

Script Execution Policy (PowerShell)

Error: Script execution is disabled

Solution:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

📚 Documentation

Project Documentation

PRD - Product Requirements Document
Architecture - Architecture Design Document
Data Model - Data Model Document
Engineering Spec - Engineering Specification
Solution Proposal - Solution Proposal

Technical Documentation

Technical Documentation - Complete technical reference
System Design - IDesign Method™ system design
Code Documentation Standards - Documentation guidelines
Developer Quick Reference - Quick reference guide

Standards & Compliance

IDesign C# Coding Standard Compliance - Coding standard compliance
IDesign Method™ Guidelines - Architecture guidelines

📝 Version

Current version: 0.0.1-alpha.1

This project follows Semantic Versioning 2.0.0. See CHANGELOG.md for complete version history and all development steps.

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

📄 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see LICENSE for details.

Why AGPL-3.0? This license ensures that any modifications or derivative works must also be open source, including when used in network services. This protects the open-source nature of the project while allowing commercial use with the requirement to contribute back improvements.

For alternative licensing options, see LICENSE-OPTIONS.md.

🧩 Extending the Toolkit

You can add:

New templates (add to /templates/)
New rulesets (add to /.cursor/rules/)
New snippets
New automation scripts (add to /scripts/)

Just keep everything inside /doc-toolkit/.

🚀 Future Enhancements

The following features are planned for future releases:

Semantic Intelligence Features

Semantic Indexing: Build vector embeddings from source files for intelligent search
- doc index - Build semantic index from source files
- Support for multiple embedding models (ONNX-based)
- Configurable chunking strategies
Semantic Search: Query project knowledge using natural language
- doc search "query" - Search across indexed content
- Top-K result ranking
- Similarity-based retrieval
Knowledge Graph Generation: Extract and visualize relationships
- doc graph - Build knowledge graph from source files
- Entity and topic extraction
- Relationship mapping
- Graph visualization (JSON, Graphviz, Markdown)
Document Summarization: Generate context summaries
- doc summarize - Create summaries of source files
- Extractive and abstractive summarization
- Context-aware summaries

These features will require:

ONNX model support (all-MiniLM-L6-v2.onnx or similar)
Microsoft.ML.OnnxRuntime NuGet package
Additional processing capabilities for embeddings and graph generation