183 lines
3.8 KiB
Markdown
183 lines
3.8 KiB
Markdown
# code-doc-cli
|
|
|
|
A CLI tool that automatically extracts documentation from code comments, function signatures, and type annotations to generate clean Markdown documentation. Supports Python, TypeScript, and Go with CI/CD integration capabilities.
|
|
|
|
## Features
|
|
|
|
- Multi-language Support: Parse Python, TypeScript, and Go source files
|
|
- Smart Comment Detection: Extract Google-style, JSDoc, and GoDoc comments
|
|
- Markdown Generation: Create well-structured documentation with syntax highlighting
|
|
- CI/CD Integration: Exit codes and flags for pipeline integration
|
|
- Configuration File: Customize behavior with `code-doc.toml`
|
|
- JSON Output: Machine-readable output for tooling integration
|
|
|
|
## Installation
|
|
|
|
### From Source
|
|
|
|
```bash
|
|
pip install -e .
|
|
```
|
|
|
|
### From PyPI
|
|
|
|
```bash
|
|
pip install code-doc-cli
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
Generate documentation for a single file:
|
|
|
|
```bash
|
|
code-doc generate myfile.py
|
|
```
|
|
|
|
Generate documentation for an entire project:
|
|
|
|
```bash
|
|
code-doc generate /path/to/project
|
|
```
|
|
|
|
Generate documentation and save to a file:
|
|
|
|
```bash
|
|
code-doc generate -o docs/API.md /path/to/project
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Basic Commands
|
|
|
|
```bash
|
|
# Generate documentation
|
|
code-doc generate <path>
|
|
|
|
# List supported languages
|
|
code-doc languages
|
|
|
|
# Initialize configuration
|
|
code-doc init
|
|
|
|
# Show version
|
|
code-doc version
|
|
```
|
|
|
|
### Options
|
|
|
|
| Option | Description |
|
|
|--------|-------------|
|
|
| `--config, -c` | Path to configuration file |
|
|
| `--language, -l` | Programming language (python, typescript, go, auto) |
|
|
| `--output, -o` | Output file path |
|
|
| `--format, -f` | Output format (markdown, json) |
|
|
| `--fail-on-warning` | Exit with error code on warnings |
|
|
| `--exclude` | Exclude patterns |
|
|
| `--include-private` | Include private members |
|
|
| `--pattern, -p` | File patterns to match |
|
|
|
|
### Examples
|
|
|
|
Generate Python documentation:
|
|
|
|
```bash
|
|
code-doc generate --language python src/
|
|
```
|
|
|
|
Generate with JSON output:
|
|
|
|
```bash
|
|
code-doc generate --format json src/ > docs.json
|
|
```
|
|
|
|
Exclude test files:
|
|
|
|
```bash
|
|
code-doc generate --exclude "**/test_*.py" src/
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Create a `code-doc.toml` file in your project root:
|
|
|
|
```toml
|
|
[tool.code-doc]
|
|
input_patterns = ["**/*.py", "**/*.ts", "**/*.go"]
|
|
output_file = "docs/API.md"
|
|
language = "auto"
|
|
template_style = "default"
|
|
syntax_highlighting = true
|
|
theme = "default"
|
|
fail_on_warning = false
|
|
exclude_patterns = ["**/test_*", "**/*_test.go"]
|
|
include_private = false
|
|
output_format = "markdown"
|
|
```
|
|
|
|
### Configuration Options
|
|
|
|
| Option | Description | Default |
|
|
|--------|-------------|---------|
|
|
| `input_patterns` | File patterns to include | All supported files |
|
|
| `output_file` | Output file path | stdout |
|
|
| `language` | Language to parse | auto-detect |
|
|
| `template_style` | Template style | default |
|
|
| `syntax_highlighting` | Enable syntax highlighting | true |
|
|
| `theme` | Syntax highlighting theme | default |
|
|
| `fail_on_warning` | Exit with error on warnings | false |
|
|
| `exclude_patterns` | Patterns to exclude | [] |
|
|
| `include_private` | Include private members | false |
|
|
| `output_format` | Output format | markdown |
|
|
|
|
## CI/CD Integration
|
|
|
|
### Exit Codes
|
|
|
|
| Code | Description |
|
|
|------|-------------|
|
|
| 0 | Success |
|
|
| 1 | No source files found |
|
|
| 2 | Parse error |
|
|
| 3 | Invalid configuration |
|
|
| 4 | Warning (with --fail-on-warning) |
|
|
|
|
## Supported Languages
|
|
|
|
### Python
|
|
|
|
Supports:
|
|
- Google-style docstrings
|
|
- NumPy-style docstrings
|
|
- Type annotations
|
|
- Class methods and attributes
|
|
- Decorators
|
|
|
|
### TypeScript/JavaScript
|
|
|
|
Supports:
|
|
- JSDoc comments
|
|
- TypeScript type signatures
|
|
- Interfaces
|
|
- Classes and methods
|
|
- Type annotations
|
|
|
|
### Go
|
|
|
|
Supports:
|
|
- GoDoc comments
|
|
- Function signatures
|
|
- Structs and interfaces
|
|
- Method receivers
|
|
- Type annotations
|
|
|
|
## Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes
|
|
4. Run tests: `pytest tests/ -v`
|
|
5. Submit a pull request
|
|
|
|
## License
|
|
|
|
MIT License |