# Doc2Man

[![CI](https://7000pct.gitea.bloupla.net/7000pctAUTO/doc2man/actions/workflows/ci.yml/badge.svg)](https://7000pct.gitea.bloupla.net/7000pctAUTO/doc2man/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](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.