doc2man/README.md

Doc2Man

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)

pip install doc2man

From source

git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/doc2man.git
cd doc2man
pip install -e .

Quick Start

Generate documentation for a Python file:

doc2man generate examples/example_python.py -o docs/command.1 -f man

Preview documentation in terminal:

doc2man preview examples/example_python.py -f markdown

Parse and display metadata:

doc2man parse examples/example_python.py

Usage

CLI Commands

generate

Generate documentation from source files.

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.

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.

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:

doc2man generate myscript.py -o myscript.1

Generate HTML documentation from directory:

doc2man generate docs/ -o reference.html -f html

Use custom template:

doc2man generate script.py -o doc.1 -t templates/custom_man.j2

Preview before generating:

doc2man generate script.py -o doc.md -f markdown --dry-run

Configuration

Create a .doc2man.yaml file in your project root:

input:
  - src/
  - lib/
output: docs/reference.1
format: man
template: templates/custom.j2
exclusions:
  - "**/test_*.py"
  - "**/__pycache__/**"

Or add to pyproject.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:

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:

// FunctionDescription performs an operation.
//
// param: Parameter description
//
// Returns: Return value description
func FunctionName(param string) string {
    return param
}

JSDoc

Standard JSDoc format:

/**
 * 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

.TH {{ title|upper|replace(' ', '_') }} 1
.SH NAME
{{ title }} \- {{ description }}
.SH SYNOPSIS
{% for func in functions %}
.B {{ func.name }}
{% endfor %}

Markdown Template

# {{ title }}

{% for func in functions %}
## {{ func.name }}

{{ func.description }}

### Parameters
| Name | Type | Description |
|------|------|-------------|
{% endfor %}

HTML Template

<!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

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

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

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 file for details.