210 lines
4.2 KiB
Markdown
210 lines
4.2 KiB
Markdown
# DocGen-CLI
|
|
|
|
A CLI tool that automatically scans codebases, detects API endpoints and function signatures, and generates beautiful interactive self-hosted API documentation with zero configuration. Works offline with no cloud dependencies.
|
|
|
|
## Features
|
|
|
|
- **Multi-language endpoint detection** - Auto-detects endpoints in Python, JavaScript, Go, and Rust codebases
|
|
- **Stripe-like interactive HTML docs** - Beautiful documentation with expandable endpoint details
|
|
- **Markdown output format** - Clean documentation suitable for GitHub Wiki
|
|
- **Live reload development server** - Watch source files and regenerate docs automatically
|
|
- **Zero configuration** - Auto-detects framework and scanning options
|
|
- **Beautiful terminal output** - Colored progress, endpoint counts, and summary information
|
|
|
|
## Installation
|
|
|
|
Install via pip:
|
|
|
|
```bash
|
|
pip install docgen-cli
|
|
```
|
|
|
|
Or install from source:
|
|
|
|
```bash
|
|
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/docgen-cli.git
|
|
cd docgen-cli
|
|
pip install -e .
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
Scan your project and generate documentation:
|
|
|
|
```bash
|
|
docgen generate
|
|
```
|
|
|
|
Start a live-reload development server:
|
|
|
|
```bash
|
|
docgen serve
|
|
```
|
|
|
|
Detect endpoints without generating docs:
|
|
|
|
```bash
|
|
docgen detect
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Generate Documentation
|
|
|
|
```bash
|
|
docgen generate [INPUT_DIR] [OPTIONS]
|
|
```
|
|
|
|
Options:
|
|
- `-o, --output DIRECTORY` - Output directory (default: `docs`)
|
|
- `-F, --format FORMAT` - Output format: `html`, `markdown`, `openapi` (default: `html`)
|
|
- `-t, --theme THEME` - Theme for HTML output (default: `default`)
|
|
- `-f, --framework FRAMEWORK` - Specific framework to use
|
|
- `--title TITLE` - Documentation title
|
|
- `-d, --description TEXT` - Documentation description
|
|
- `-v, --version VERSION` - API version
|
|
- `--verbose` - Enable verbose output
|
|
|
|
### Serve Documentation
|
|
|
|
```bash
|
|
docgen serve [DOCS_DIR] [OPTIONS]
|
|
```
|
|
|
|
Options:
|
|
- `-h, --host HOST` - Host to bind to (default: `127.0.0.1`)
|
|
- `-p, --port PORT` - Port to bind to (default: `8000`)
|
|
- `--no-reload` - Disable auto-reload on changes
|
|
|
|
### Detect Endpoints
|
|
|
|
```bash
|
|
docgen detect [INPUT_DIR] [OPTIONS]
|
|
```
|
|
|
|
Options:
|
|
- `-f, --framework FRAMEWORK` - Specific framework to use
|
|
- `--no-recursive` - Disable recursive scanning
|
|
|
|
### Initialize Configuration
|
|
|
|
```bash
|
|
docgen init --output .
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Create a `docgen.toml` file to customize behavior:
|
|
|
|
```toml
|
|
[tool.docgen]
|
|
input-dir = "."
|
|
output-dir = "docs"
|
|
format = "html"
|
|
theme = "default"
|
|
title = "My API"
|
|
version = "1.0.0"
|
|
```
|
|
|
|
### Environment Variables
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `DOCGEN_OUTPUT` | `docs` | Output directory |
|
|
| `DOCGEN_FORMAT` | `html` | Output format |
|
|
| `DOCGEN_THEME` | `default` | Theme name |
|
|
| `DOCGEN_VERBOSE` | `false` | Enable verbose output |
|
|
|
|
## Supported Frameworks
|
|
|
|
### Python
|
|
- FastAPI
|
|
- Flask
|
|
- Django
|
|
|
|
### JavaScript/TypeScript
|
|
- Express
|
|
- Fastify
|
|
|
|
### Go
|
|
- Gin
|
|
- chi
|
|
|
|
### Rust
|
|
- Actix-web
|
|
|
|
## Output Formats
|
|
|
|
### HTML
|
|
Interactive documentation with:
|
|
- Expandable endpoint details
|
|
- Method badges with color coding
|
|
- Interactive cURL generator
|
|
- Sidebar navigation with search
|
|
- Responsive design
|
|
|
|
### Markdown
|
|
Clean Markdown documentation with:
|
|
- Endpoint tables
|
|
- Parameter documentation
|
|
- Response examples
|
|
- GitHub-compatible formatting
|
|
|
|
### OpenAPI
|
|
Standard OpenAPI 3.0 specification:
|
|
- JSON output
|
|
- Compatible with Swagger UI
|
|
- Full schema support
|
|
- Security definitions
|
|
|
|
## Examples
|
|
|
|
### Basic FastAPI Documentation
|
|
|
|
```python
|
|
from fastapi import FastAPI
|
|
|
|
app = FastAPI()
|
|
|
|
@app.get("/users", tags=["users"])
|
|
async def list_users():
|
|
"""List all users"""
|
|
return {"users": []}
|
|
|
|
@app.post("/users", tags=["users"])
|
|
async def create_user(name: str):
|
|
"""Create a new user"""
|
|
return {"id": 1, "name": name}
|
|
```
|
|
|
|
Generate docs:
|
|
|
|
```bash
|
|
docgen generate --title "User API" --format html
|
|
```
|
|
|
|
### Express.js Documentation
|
|
|
|
```javascript
|
|
const express = require('express');
|
|
const router = express.Router();
|
|
|
|
router.get('/items', (req, res) => {
|
|
res.json({ items: [] });
|
|
});
|
|
|
|
router.post('/items', (req, res) => {
|
|
res.status(201).json({ id: 1 });
|
|
});
|
|
```
|
|
|
|
Generate docs:
|
|
|
|
```bash
|
|
docgen generate --framework javascript --format markdown
|
|
```
|
|
|
|
## License
|
|
|
|
MIT License - see LICENSE file for details.
|