348 lines
7.0 KiB
Markdown
348 lines
7.0 KiB
Markdown
# Doc2Man
|
|
|
|
[](https://7000pct.gitea.bloupla.net/7000pctAUTO/doc2man/actions)
|
|
[](https://opensource.org/licenses/MIT)
|
|
[](https://www.python.org/downloads/)
|
|
|
|
Doc2Man is a CLI tool that automatically generates man pages, Markdown, and HTML documentation from docstrings in Python, Go, and JavaScript source code. It parses function descriptions, arguments, and examples, then formats them using customizable templates. Perfect for open-source CLI developers who need professional documentation without manual formatting.
|
|
|
|
## Features
|
|
|
|
- **Multi-language support**: Parse docstrings from Python, Go, and JavaScript/TypeScript files
|
|
- **Multiple output formats**: Generate man pages (troff), Markdown, and HTML documentation
|
|
- **Custom templates**: Use Jinja2 templates for complete control over output
|
|
- **Configuration files**: Project-wide settings via YAML or pyproject.toml
|
|
- **CI/CD integration**: Exit codes, dry-run mode, and build artifact support
|
|
- **Terminal preview**: Preview documentation before generation
|
|
|
|
## Installation
|
|
|
|
### From PyPI (recommended)
|
|
|
|
```bash
|
|
pip install doc2man
|
|
```
|
|
|
|
### From source
|
|
|
|
```bash
|
|
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/doc2man.git
|
|
cd doc2man
|
|
pip install -e .
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
Generate documentation for a Python file:
|
|
|
|
```bash
|
|
doc2man generate examples/example_python.py -o docs/command.1 -f man
|
|
```
|
|
|
|
Preview documentation in terminal:
|
|
|
|
```bash
|
|
doc2man preview examples/example_python.py -f markdown
|
|
```
|
|
|
|
Parse and display metadata:
|
|
|
|
```bash
|
|
doc2man parse examples/example_python.py
|
|
```
|
|
|
|
## Usage
|
|
|
|
### CLI Commands
|
|
|
|
#### generate
|
|
|
|
Generate documentation from source files.
|
|
|
|
```bash
|
|
doc2man generate INPUT_PATH [INPUT_PATH...] -o OUTPUT -f FORMAT [OPTIONS]
|
|
```
|
|
|
|
Options:
|
|
- `-o, --output`: Output file path (required)
|
|
- `-f, --format`: Output format (man, markdown, html) [default: man]
|
|
- `-t, --template`: Custom template file
|
|
- `--dry-run`: Preview output without writing files
|
|
- `--fail-on-error`: Exit with non-zero code on any error
|
|
|
|
#### preview
|
|
|
|
Preview documentation in terminal.
|
|
|
|
```bash
|
|
doc2man preview INPUT_PATH [INPUT_PATH...] [OPTIONS]
|
|
```
|
|
|
|
Options:
|
|
- `-f, --format`: Preview format (man, markdown, html) [default: man]
|
|
|
|
#### parse
|
|
|
|
Parse a single file and display parsed metadata.
|
|
|
|
```bash
|
|
doc2man parse INPUT_FILE [OPTIONS]
|
|
```
|
|
|
|
Options:
|
|
- `-f, --format`: Output format (man, markdown, html)
|
|
- `-o, --output`: Write output to file
|
|
|
|
### Examples
|
|
|
|
Generate man page from Python file:
|
|
|
|
```bash
|
|
doc2man generate myscript.py -o myscript.1
|
|
```
|
|
|
|
Generate HTML documentation from directory:
|
|
|
|
```bash
|
|
doc2man generate docs/ -o reference.html -f html
|
|
```
|
|
|
|
Use custom template:
|
|
|
|
```bash
|
|
doc2man generate script.py -o doc.1 -t templates/custom_man.j2
|
|
```
|
|
|
|
Preview before generating:
|
|
|
|
```bash
|
|
doc2man generate script.py -o doc.md -f markdown --dry-run
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Create a `.doc2man.yaml` file in your project root:
|
|
|
|
```yaml
|
|
input:
|
|
- src/
|
|
- lib/
|
|
output: docs/reference.1
|
|
format: man
|
|
template: templates/custom.j2
|
|
exclusions:
|
|
- "**/test_*.py"
|
|
- "**/__pycache__/**"
|
|
```
|
|
|
|
Or add to `pyproject.toml`:
|
|
|
|
```toml
|
|
[tool.doc2man]
|
|
input = ["src/"]
|
|
output = "docs/manual.1"
|
|
format = "man"
|
|
exclusions = ["**/test_*.py"]
|
|
```
|
|
|
|
### Configuration Options
|
|
|
|
| Option | Type | Description |
|
|
|--------|------|-------------|
|
|
| `input` | list | Input files or directories to parse |
|
|
| `output` | string | Output file path |
|
|
| `format` | string | Output format (man, markdown, html) |
|
|
| `template` | string | Custom template file path |
|
|
| `exclusions` | list | File patterns to exclude |
|
|
|
|
## Supported Formats
|
|
|
|
### Python Docstrings
|
|
|
|
Supports Google-style, NumPy-style, and ReST formats:
|
|
|
|
```python
|
|
def example(name, value=None):
|
|
"""Function description.
|
|
|
|
Args:
|
|
name: Parameter description.
|
|
value: Optional parameter.
|
|
|
|
Returns:
|
|
Return value description.
|
|
|
|
Raises:
|
|
ValueError: Error description.
|
|
|
|
Examples:
|
|
>>> example("test")
|
|
"""
|
|
```
|
|
|
|
### Go Documentation
|
|
|
|
Standard Go documentation comments:
|
|
|
|
```go
|
|
// FunctionDescription performs an operation.
|
|
//
|
|
// param: Parameter description
|
|
//
|
|
// Returns: Return value description
|
|
func FunctionName(param string) string {
|
|
return param
|
|
}
|
|
```
|
|
|
|
### JSDoc
|
|
|
|
Standard JSDoc format:
|
|
|
|
```javascript
|
|
/**
|
|
* Function description.
|
|
*
|
|
* @param {string} param - Parameter description
|
|
* @returns {string} Return value description
|
|
* @throws {Error} Error description
|
|
*/
|
|
```
|
|
|
|
## Custom Templates
|
|
|
|
Doc2Man uses Jinja2 templates. Create custom templates for each format:
|
|
|
|
### Man Page Template
|
|
|
|
```jinja2
|
|
.TH {{ title|upper|replace(' ', '_') }} 1
|
|
.SH NAME
|
|
{{ title }} \- {{ description }}
|
|
.SH SYNOPSIS
|
|
{% for func in functions %}
|
|
.B {{ func.name }}
|
|
{% endfor %}
|
|
```
|
|
|
|
### Markdown Template
|
|
|
|
```jinja2
|
|
# {{ title }}
|
|
|
|
{% for func in functions %}
|
|
## {{ func.name }}
|
|
|
|
{{ func.description }}
|
|
|
|
### Parameters
|
|
| Name | Type | Description |
|
|
|------|------|-------------|
|
|
{% endfor %}
|
|
```
|
|
|
|
### HTML Template
|
|
|
|
```jinja2
|
|
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<title>{{ title }}</title>
|
|
</head>
|
|
<body>
|
|
<h1>{{ title }}</h1>
|
|
{% for func in functions %}
|
|
<h2>{{ func.name }}</h2>
|
|
{% endfor %}
|
|
</body>
|
|
</html>
|
|
```
|
|
|
|
## CI/CD Integration
|
|
|
|
### Gitea Actions
|
|
|
|
```yaml
|
|
name: Generate Documentation
|
|
|
|
on:
|
|
release:
|
|
types: [published]
|
|
|
|
jobs:
|
|
docs:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v4
|
|
- name: Set up Python
|
|
uses: actions/setup-python@v5
|
|
with:
|
|
python-version: '3.11'
|
|
- name: Install doc2man
|
|
run: pip install doc2man
|
|
- name: Generate man page
|
|
run: doc2man generate src/ -o docs/command.1 -f man
|
|
- name: Upload artifact
|
|
uses: actions/upload-artifact@v4
|
|
with:
|
|
name: man-pages
|
|
path: docs/
|
|
```
|
|
|
|
### GitLab CI
|
|
|
|
```yaml
|
|
generate-docs:
|
|
image: python:3.11
|
|
script:
|
|
- pip install doc2man
|
|
- doc2man generate src/ -o public/man/command.1
|
|
artifacts:
|
|
paths:
|
|
- public/man/
|
|
```
|
|
|
|
### Exit Codes
|
|
|
|
- `0`: Success
|
|
- `1`: General error
|
|
- `2`: No documentation found
|
|
- `3`: Invalid configuration
|
|
|
|
Use `--fail-on-error` for strict mode in CI pipelines.
|
|
|
|
## API Reference
|
|
|
|
### Python API
|
|
|
|
```python
|
|
from doc2man.parsers.python import parse_python_file
|
|
from doc2man.generators.man import generate_man_page
|
|
from doc2man.generators.markdown import generate_markdown
|
|
from doc2man.generators.html import generate_html
|
|
|
|
# Parse Python file
|
|
parsed = parse_python_file("myfile.py")
|
|
|
|
# Generate man page
|
|
generate_man_page([{"file": "myfile.py", "data": parsed}], "output.1")
|
|
|
|
# Generate markdown
|
|
generate_markdown([{"file": "myfile.py", "data": parsed}], "output.md")
|
|
|
|
# Generate HTML
|
|
generate_html([{"file": "myfile.py", "data": parsed}], "output.html")
|
|
```
|
|
|
|
## 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 - see [LICENSE](LICENSE) file for details.
|