pydoc2markdown 0.1.0__py3-none-any.whl

pydoc2markdown/__init__.py

@@ -0,0 +1,26 @@
+"""PyDoc2Markdown - Convert Python docstrings to Markdown documentation."""
+
+__version__ = "0.1.0"
+__author__ = "f1sherFM"
+
+from pydoc2markdown.core.generator import MarkdownGenerator
+from pydoc2markdown.core.parser import (
+    ClassDoc,
+    DocstringParser,
+    FunctionDoc,
+    ModuleDoc,
+    Parameter,
+    RaisesInfo,
+    ReturnsInfo,
+)
+
+__all__ = [
+    "ClassDoc",
+    "DocstringParser",
+    "FunctionDoc",
+    "MarkdownGenerator",
+    "ModuleDoc",
+    "Parameter",
+    "RaisesInfo",
+    "ReturnsInfo",
+]

pydoc2markdown/cli.py

@@ -0,0 +1,131 @@
+"""Command-line interface for PyDoc2Markdown."""
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+
+from pydoc2markdown.core.config import load_config
+from pydoc2markdown.core.generator import MarkdownGenerator
+from pydoc2markdown.core.parser import DocstringParser
+from pydoc2markdown.core.watcher import watch_and_generate
+
+logger = logging.getLogger(__name__)
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """Create and configure the argument parser."""
+    defaults = load_config()
+    parser = argparse.ArgumentParser(
+        prog="pydoc2markdown",
+        description="Convert Python docstrings to Markdown documentation.",
+    )
+    parser.add_argument(
+        "source",
+        type=Path,
+        help="Path to a Python file or directory to process.",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        default=Path(str(defaults.get("output", "docs"))),
+        help="Output directory for generated Markdown files (default: docs).",
+    )
+    parser.add_argument(
+        "--recursive",
+        action="store_true",
+        default=defaults.get("recursive", False),
+        help="Recursively process subdirectories.",
+    )
+    parser.add_argument(
+        "--template",
+        type=Path,
+        default=None,
+        help="Path to a custom Jinja2 template for Markdown generation.",
+    )
+    parser.add_argument(
+        "--theme",
+        choices=["default", "minimal"],
+        default=defaults.get("theme", "default"),
+        help="Built-in theme/template to use (default: default).",
+    )
+    parser.add_argument(
+        "--watch",
+        action="store_true",
+        help="Watch source files and regenerate docs on change.",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="count",
+        default=0,
+        help="Increase verbosity (-v for INFO, -vv for DEBUG).",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version="%(prog)s 0.1.0",
+    )
+    return parser
+
+
+def _setup_logging(verbosity: int) -> None:
+    """Configure logging level based on verbosity count."""
+    level = logging.WARNING
+    if verbosity >= 2:
+        level = logging.DEBUG
+    elif verbosity == 1:
+        level = logging.INFO
+    logging.basicConfig(
+        level=level,
+        format="%(name)s - %(levelname)s - %(message)s",
+    )
+
+
+def main(args: list[str] | None = None) -> int:
+    """Main entry point for the CLI."""
+    parser = create_parser()
+    parsed_args = parser.parse_args(args)
+    _setup_logging(parsed_args.verbose)
+
+    if not parsed_args.source.exists():
+        logger.error("Source path does not exist: %s", parsed_args.source)
+        return 1
+
+    if parsed_args.watch:
+        return watch_and_generate(
+            source=parsed_args.source,
+            output_dir=parsed_args.output,
+            recursive=parsed_args.recursive,
+            theme=parsed_args.theme,
+            template_path=parsed_args.template,
+        )
+
+    logger.info("Parsing source: %s (recursive=%s)", parsed_args.source, parsed_args.recursive)
+    doc_parser = DocstringParser()
+    md_generator = MarkdownGenerator(
+        template_path=parsed_args.template,
+        theme=parsed_args.theme,
+    )
+
+    try:
+        modules = doc_parser.parse(
+            source=parsed_args.source,
+            recursive=parsed_args.recursive,
+        )
+        logger.info("Parsed %d module(s)", len(modules))
+        generated = md_generator.generate(
+            modules=modules,
+            output_dir=parsed_args.output,
+        )
+        logger.info("Generated %d Markdown file(s) in %s", len(generated), parsed_args.output)
+    except Exception:
+        logger.exception("Documentation generation failed")
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pydoc2markdown/core/__init__.py

@@ -0,0 +1 @@
+"""Core logic for PyDoc2Markdown."""

pydoc2markdown/core/config.py

@@ -0,0 +1,39 @@
+"""Configuration loader for PyDoc2Markdown."""
+
+import logging
+from pathlib import Path
+from typing import Any, cast
+
+logger = logging.getLogger(__name__)
+
+
+def load_config(
+    cwd: Path | None = None,
+) -> dict[str, Any]:
+    """Load [tool.pydoc2markdown] from pyproject.toml.
+
+    Args:
+        cwd: Directory to search for pyproject.toml. Defaults to current dir.
+
+    Returns:
+        Dictionary with parsed config values.
+    """
+    try:
+        import tomllib
+    except ModuleNotFoundError:
+        import tomli as tomllib
+
+    if cwd is None:
+        cwd = Path.cwd()
+
+    pyproject = cwd / "pyproject.toml"
+    if not pyproject.exists():
+        return {}
+
+    try:
+        with pyproject.open("rb") as f:
+            data = tomllib.load(f)
+        return cast(dict[str, Any], data.get("tool", {}).get("pydoc2markdown", {}))
+    except Exception:
+        logger.warning("Failed to load pyproject.toml config")
+        return {}

pydoc2markdown/core/generator.py

@@ -0,0 +1,271 @@
+"""Markdown documentation generator."""
+
+import logging
+from pathlib import Path
+
+from jinja2 import Environment, FileSystemLoader, PackageLoader, select_autoescape
+
+from pydoc2markdown.core.parser import ModuleDoc
+
+logger = logging.getLogger(__name__)
+
+
+class MarkdownGenerator:
+    """Generate Markdown files from parsed Python documentation."""
+
+    DEFAULT_TEMPLATE = """# {{ module.name }}
+
+{% if module.docstring %}
+{{ module.docstring }}
+{% endif %}
+
+{% if module.classes or module.functions %}
+## Table of Contents
+
+{% if module.classes %}
+- [Classes](#classes)
+{% for class in module.classes %}
+  - [`{{ class.name }}`](#{{ class.name | lower | replace(' ', '-') }})
+{% if class.methods %}
+{% for method in class.methods %}
+    - [
+{% if method.is_property %}@property {% elif method.is_classmethod %}@classmethod
+{% elif method.is_staticmethod %}@staticmethod {% endif %}
+`{{ method.name }}`](#{{ method.name | lower | replace(' ', '-') }})
+{% endfor %}
+{% endif %}
+{% endfor %}
+{% endif %}
+{% if module.functions %}
+- [Functions](#functions)
+{% for func in module.functions %}
+  - [`{{ func.name }}`](#{{ func.name | lower | replace(' ', '-') }})
+{% endfor %}
+{% endif %}
+{% endif %}
+
+{% if module.public_api %}
+**Public API:**
+{% for name in module.public_api %}
+- `{{ name }}`
+{% endfor %}
+{% endif %}
+
+{% if module.classes %}
+## Classes
+
+{% for class in module.classes %}
+### `{{ class.name }}`{% if class.class_type != "class" %} ({{ class.class_type }}){% endif %}
+
+{% if class.bases %}
+**Bases:** `{{ class.bases | join(", ") }}`
+{% endif %}
+
+{% if class.docstring %}
+{{ class.docstring }}
+{% endif %}
+
+{% if class.attributes %}
+#### Attributes
+
+| Name | Type | Description |
+|------|------|-------------|
+{% for attr in class.attributes %}
+| `{{ attr.name }}` |
+{% if attr.type_hint %}`{{ attr.type_hint }}`{% else %}-{% endif %} |
+{% if attr.description %}{{ attr.description }}{% else %}-{% endif %} |
+{% endfor %}
+{% endif %}
+
+{% if class.methods %}
+#### Methods
+
+{% for method in class.methods %}
+{% if method.is_property %}##### @property `{{ method.name }}`
+{% elif method.is_classmethod %}##### @classmethod `{{ method.name }}`
+{% elif method.is_staticmethod %}##### @staticmethod `{{ method.name }}`
+{% else %}##### `{{ method.name }}`
+{% endif %}
+
+{% if method.docstring %}
+{{ method.docstring }}
+{% endif %}
+
+{% if method.params %}
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+{% for param in method.params %}
+| `{{ param.name }}` |
+{% if param.type_hint %}`{{ param.type_hint }}`{% else %}-{% endif %} |
+{% if param.description %}{{ param.description }}{% else %}-{% endif %} |
+{% endfor %}
+{% endif %}
+
+{% if method.returns %}
+**Returns:**{% if method.returns.type_hint %} `{{ method.returns.type_hint }}`{% endif %}
+
+{% if method.returns.description %}{{ method.returns.description }}{% endif %}
+{% endif %}
+
+{% if method.raises %}
+**Raises:**
+{% for raise in method.raises %}
+- {% if raise.type_name %}`{{ raise.type_name }}`{% endif %}
+{% if raise.description %}: {{ raise.description }}{% endif %}
+{% endfor %}
+{% endif %}
+
+{% endfor %}
+{% endif %}
+
+---
+{% endfor %}
+{% endif %}
+
+{% if module.functions %}
+## Functions
+
+{% for func in module.functions %}
+### `{{ func.name }}`
+
+{% if func.docstring %}
+{{ func.docstring }}
+{% endif %}
+
+{% if func.params %}
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+{% for param in func.params %}
+| `{{ param.name }}` |
+{% if param.type_hint %}`{{ param.type_hint }}`{% else %}-{% endif %} |
+{% if param.description %}{{ param.description }}{% else %}-{% endif %} |
+{% endfor %}
+{% endif %}
+
+{% if func.returns %}
+**Returns:**{% if func.returns.type_hint %} `{{ func.returns.type_hint }}`{% endif %}
+
+{% if func.returns.description %}{{ func.returns.description }}{% endif %}
+{% endif %}
+
+{% if func.raises %}
+**Raises:**
+{% for raise in func.raises %}
+- {% if raise.type_name %}`{{ raise.type_name }}`{% endif %}
+{% if raise.description %}: {{ raise.description }}{% endif %}
+{% endfor %}
+{% endif %}
+
+{% endfor %}
+{% endif %}
+"""
+
+    def __init__(
+        self,
+        template_path: Path | None = None,
+        theme: str = "default",
+    ) -> None:
+        """Initialize the generator with an optional custom template or theme."""
+        self._template_path = template_path
+        self._theme = theme
+        self._env = self._create_environment()
+
+    def _create_environment(self) -> Environment:
+        """Create and configure the Jinja2 environment."""
+        if self._template_path and self._template_path.exists():
+            return Environment(
+                loader=FileSystemLoader(str(self._template_path.parent)),
+                autoescape=select_autoescape(),
+            )
+        return Environment(
+            loader=PackageLoader("pydoc2markdown", "templates"),
+            autoescape=select_autoescape(),
+        )
+
+    def _resolve_template_name(self) -> str:
+        """Resolve the template file name based on theme or custom path."""
+        if self._template_path:
+            return self._template_path.name
+        if self._theme == "default":
+            return "module.md"
+        return f"{self._theme}.md"
+
+    def generate(
+        self,
+        modules: list[ModuleDoc],
+        output_dir: Path,
+    ) -> list[Path]:
+        """Generate Markdown files for the given modules."""
+        output_dir.mkdir(parents=True, exist_ok=True)
+        generated: list[Path] = []
+
+        template_name = self._resolve_template_name()
+        logger.debug("Using template: %s", template_name)
+        template = self._env.get_template(template_name)
+
+        for module in modules:
+            if module.package:
+                module_dir = output_dir / module.package.replace(".", "/")
+                module_dir.mkdir(parents=True, exist_ok=True)
+                output_path = module_dir / f"{module.name}.md"
+            else:
+                output_path = output_dir / f"{module.name}.md"
+            logger.debug("Generating %s", output_path)
+            content = template.render(module=module)
+            output_path.write_text(content, encoding="utf-8")
+            generated.append(output_path)
+
+        index_path = self._generate_index(modules, output_dir)
+        if index_path:
+            generated.append(index_path)
+
+        return generated
+
+    def _generate_index(
+        self,
+        modules: list[ModuleDoc],
+        output_dir: Path,
+    ) -> Path | None:
+        """Generate an index.md with links to all module docs, grouped by package."""
+        if not modules:
+            return None
+
+        from collections import OrderedDict
+
+        groups: OrderedDict[str, list[ModuleDoc]] = OrderedDict()
+        for module in sorted(modules, key=lambda m: (m.package, m.name)):
+            groups.setdefault(module.package, []).append(module)
+
+        lines = ["# Index", ""]
+        for package, mods in groups.items():
+            if package:
+                lines.append(f"## {package}")
+            else:
+                lines.append("## Modules")
+            for module in mods:
+                rel_path = (
+                    f"{module.package.replace('.', '/')}/{module.name}.md"
+                    if module.package
+                    else f"{module.name}.md"
+                )
+                lines.append(f"- [{module.name}]({rel_path})")
+                if module.docstring:
+                    first_line = module.docstring.split("\n")[0]
+                    lines.append(f"  - {first_line}")
+            lines.append("")
+
+        index_path = output_dir / "index.md"
+        logger.debug("Generating %s", index_path)
+        index_path.write_text("\n".join(lines), encoding="utf-8")
+        return index_path
+
+    def generate_string(self, module: ModuleDoc) -> str:
+        """Generate Markdown content as a string for a single module."""
+        from jinja2 import Template
+
+        template = Template(self.DEFAULT_TEMPLATE)
+        return template.render(module=module)

pydoc2markdown/core/parser.py

@@ -0,0 +1,396 @@
+"""Python docstring parser with structured docstring support."""
+
+import ast
+import contextlib
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import docstring_parser
+from docstring_parser import Docstring as ParsedDocstring
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Parameter:
+    """Represents a function/method parameter."""
+
+    name: str
+    type_hint: str | None = None
+    default: str | None = None
+    description: str | None = None
+
+
+@dataclass
+class ReturnsInfo:
+    """Structured return type and description."""
+
+    type_hint: str | None = None
+    description: str | None = None
+
+
+@dataclass
+class RaisesInfo:
+    """Structured exception type and description."""
+
+    type_name: str | None = None
+    description: str | None = None
+
+
+@dataclass
+class FunctionDoc:
+    """Represents extracted documentation for a function or method."""
+
+    name: str
+    docstring: str | None = None
+    params: list[Parameter] = field(default_factory=list)
+    returns: ReturnsInfo | None = None
+    raises: list[RaisesInfo] = field(default_factory=list)
+    is_method: bool = False
+    is_async: bool = False
+    is_property: bool = False
+    is_classmethod: bool = False
+    is_staticmethod: bool = False
+
+
+@dataclass
+class ClassDoc:
+    """Represents extracted documentation for a class."""
+
+    name: str
+    docstring: str | None = None
+    methods: list[FunctionDoc] = field(default_factory=list)
+    attributes: list[Parameter] = field(default_factory=list)
+    bases: list[str] = field(default_factory=list)
+    class_type: str = "class"
+
+
+@dataclass
+class ModuleDoc:
+    """Represents extracted documentation for a module."""
+
+    name: str
+    path: Path
+    docstring: str | None = None
+    classes: list[ClassDoc] = field(default_factory=list)
+    functions: list[FunctionDoc] = field(default_factory=list)
+    public_api: list[str] = field(default_factory=list)
+    package: str = ""
+
+
+class DocstringParser:
+    """Parse Python source files and extract structured docstrings."""
+
+    def __init__(self) -> None:
+        self._modules: list[ModuleDoc] = []
+        self._source: Path = Path()
+
+    def parse(
+        self,
+        source: Path,
+        recursive: bool = False,
+    ) -> list[ModuleDoc]:
+        """Parse a file or directory and return extracted documentation."""
+        self._modules.clear()
+        self._source = source
+
+        if source.is_file() and source.suffix == ".py":
+            self._parse_file(source)
+        elif source.is_dir():
+            pattern = "**/*.py" if recursive else "*.py"
+            for file_path in sorted(source.glob(pattern)):
+                self._parse_file(file_path)
+        else:
+            raise ValueError(f"Invalid source: {source}")
+
+        return self._modules
+
+    def _parse_file(self, path: Path) -> None:
+        """Parse a single Python file."""
+        logger.debug("Parsing file: %s", path)
+        try:
+            source_text = path.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            source_text = path.read_text(encoding="latin-1")
+
+        tree = ast.parse(source_text)
+        module_doc = self._extract_module(path, tree)
+        logger.debug(
+            "Extracted %d classes and %d functions from %s",
+            len(module_doc.classes),
+            len(module_doc.functions),
+            path,
+        )
+        self._modules.append(module_doc)
+
+    def _extract_module(self, path: Path, tree: ast.AST) -> ModuleDoc:
+        """Extract module-level documentation."""
+        assert isinstance(tree, ast.Module)
+        package = ""
+        if self._source.is_dir():
+            try:
+                rel = path.parent.relative_to(self._source)
+                if rel != Path("."):
+                    package = str(rel).replace("\\", ".").replace("/", ".")
+            except ValueError:
+                package = ""
+        module = ModuleDoc(
+            name=path.stem,
+            path=path,
+            docstring=ast.get_docstring(tree),
+            package=package,
+        )
+
+        for node in ast.iter_child_nodes(tree):
+            if isinstance(node, ast.ClassDef):
+                module.classes.append(self._extract_class(node))
+            elif isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
+                module.functions.append(self._extract_function(node))
+            elif isinstance(node, ast.Assign | ast.AnnAssign):
+                module.public_api.extend(self._extract_public_api(node))
+
+        return module
+
+    def _extract_class(self, node: ast.ClassDef) -> ClassDoc:
+        """Extract documentation from a class definition."""
+        bases = [self._format_base(base) for base in node.bases]
+        class_doc = ClassDoc(
+            name=node.name,
+            docstring=ast.get_docstring(node),
+            bases=bases,
+            class_type=self._resolve_class_type(node, bases),
+        )
+
+        for item in node.body:
+            if isinstance(item, ast.FunctionDef | ast.AsyncFunctionDef):
+                if item.name == "__init__":
+                    class_doc.attributes.extend(self._extract_attributes(item))
+                else:
+                    class_doc.methods.append(self._extract_function(item, is_method=True))
+
+        return class_doc
+
+    def _extract_function(
+        self,
+        node: ast.FunctionDef | ast.AsyncFunctionDef,
+        is_method: bool = False,
+    ) -> FunctionDoc:
+        """Extract documentation from a function definition."""
+        raw_docstring = ast.get_docstring(node)
+        params = self._extract_ast_params(node)
+        returns: ReturnsInfo | None = None
+        raises: list[RaisesInfo] = []
+
+        if raw_docstring:
+            with contextlib.suppress(Exception):
+                parsed = docstring_parser.parse(raw_docstring)
+                self._merge_param_descriptions(params, parsed)
+                returns = self._extract_returns(parsed)
+                raises = self._extract_raises(parsed)
+
+        # Fallback to AST return annotation if docstring did not provide type
+        ast_return_type = ast.unparse(node.returns) if node.returns else None
+        if returns is None:
+            returns = ReturnsInfo(type_hint=ast_return_type)
+        elif ast_return_type and not returns.type_hint:
+            returns.type_hint = ast_return_type
+
+        decorators = self._extract_decorator_names(node)
+        is_property = any(d in ("property", "cached_property") for d in decorators)
+        is_classmethod = "classmethod" in decorators
+        is_staticmethod = "staticmethod" in decorators
+
+        return FunctionDoc(
+            name=node.name,
+            docstring=raw_docstring,
+            params=params,
+            returns=returns,
+            raises=raises,
+            is_method=is_method,
+            is_async=isinstance(node, ast.AsyncFunctionDef),
+            is_property=is_property,
+            is_classmethod=is_classmethod,
+            is_staticmethod=is_staticmethod,
+        )
+
+    def _extract_ast_params(
+        self,
+        node: ast.FunctionDef | ast.AsyncFunctionDef,
+    ) -> list[Parameter]:
+        """Extract parameter names and type hints from AST."""
+        params: list[Parameter] = []
+        args = node.args
+
+        # Determine start index (skip self/cls for methods)
+        start = 0
+        if args.args and args.args[0].arg in ("self", "cls"):
+            start = 1
+
+        # Positional args
+        for _idx, arg in enumerate(args.args[start:], start=start):
+            param = Parameter(
+                name=arg.arg,
+                type_hint=ast.unparse(arg.annotation) if arg.annotation else None,
+            )
+            params.append(param)
+
+        # *args
+        if args.vararg:
+            params.append(
+                Parameter(
+                    name=f"*{args.vararg.arg}",
+                    type_hint=ast.unparse(args.vararg.annotation)
+                    if args.vararg.annotation
+                    else None,
+                ),
+            )
+
+        # Keyword-only args
+        for arg in args.kwonlyargs:
+            params.append(
+                Parameter(
+                    name=arg.arg,
+                    type_hint=ast.unparse(arg.annotation) if arg.annotation else None,
+                ),
+            )
+
+        # **kwargs
+        if args.kwarg:
+            params.append(
+                Parameter(
+                    name=f"**{args.kwarg.arg}",
+                    type_hint=ast.unparse(args.kwarg.annotation) if args.kwarg.annotation else None,
+                ),
+            )
+
+        return params
+
+    def _merge_param_descriptions(
+        self,
+        params: list[Parameter],
+        parsed: ParsedDocstring,
+    ) -> None:
+        """Merge docstring parameter descriptions into AST-extracted parameters."""
+        for param in params:
+            doc_param = next(
+                (p for p in parsed.params if p.arg_name == param.name.lstrip("*")),
+                None,
+            )
+            if doc_param and doc_param.description:
+                param.description = doc_param.description
+
+    def _extract_returns(self, parsed: ParsedDocstring) -> ReturnsInfo | None:
+        """Extract structured return info from parsed docstring."""
+        if parsed.returns:
+            return ReturnsInfo(
+                type_hint=parsed.returns.type_name,
+                description=parsed.returns.description,
+            )
+        return None
+
+    def _extract_raises(self, parsed: ParsedDocstring) -> list[RaisesInfo]:
+        """Extract structured raises info from parsed docstring."""
+        return [
+            RaisesInfo(
+                type_name=r.type_name,
+                description=r.description,
+            )
+            for r in parsed.raises
+        ]
+
+    def _extract_attributes(
+        self,
+        init_node: ast.FunctionDef | ast.AsyncFunctionDef,
+    ) -> list[Parameter]:
+        """Extract instance attributes from __init__ method."""
+        attributes: list[Parameter] = []
+
+        # Try to enrich with __init__ docstring parameter descriptions
+        init_docstring = ast.get_docstring(init_node)
+        parsed_init: ParsedDocstring | None = None
+        if init_docstring:
+            with contextlib.suppress(Exception):
+                parsed_init = docstring_parser.parse(init_docstring)
+
+        for node in ast.walk(init_node):
+            if (
+                isinstance(node, ast.AnnAssign)
+                and isinstance(node.target, ast.Attribute)
+                and isinstance(node.target.value, ast.Name)
+                and node.target.value.id == "self"
+            ):
+                attr_name = node.target.attr
+                attr = Parameter(
+                    name=attr_name,
+                    type_hint=ast.unparse(node.annotation) if node.annotation else None,
+                )
+                if parsed_init:
+                    doc_attr = next(
+                        (p for p in parsed_init.params if p.arg_name == attr_name),
+                        None,
+                    )
+                    if doc_attr and doc_attr.description:
+                        attr.description = doc_attr.description
+                attributes.append(attr)
+
+        return attributes
+
+    def _format_base(self, base: ast.expr) -> str:
+        """Format a base class expression as a string."""
+        return ast.unparse(base)
+
+    def _extract_decorator_names(
+        self,
+        node: ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef,
+    ) -> list[str]:
+        """Extract decorator names from a function or class definition."""
+        names: list[str] = []
+        for dec in node.decorator_list:
+            if isinstance(dec, ast.Name):
+                names.append(dec.id)
+            elif isinstance(dec, ast.Attribute):
+                names.append(f"{ast.unparse(dec.value)}.{dec.attr}")
+            elif isinstance(dec, ast.Call):
+                if isinstance(dec.func, ast.Name):
+                    names.append(dec.func.id)
+                elif isinstance(dec.func, ast.Attribute):
+                    names.append(f"{ast.unparse(dec.func.value)}.{dec.func.attr}")
+        return names
+
+    def _resolve_class_type(
+        self,
+        node: ast.ClassDef,
+        bases: list[str],
+    ) -> str:
+        """Determine if a class is a dataclass, enum, typeddict, or plain class."""
+        decorators = self._extract_decorator_names(node)
+        if any(d in ("dataclass", "dataclasses.dataclass") for d in decorators):
+            return "dataclass"
+        if any(base.rsplit(".", 1)[-1] in ("Enum", "IntEnum", "Flag", "IntFlag") for base in bases):
+            return "enum"
+        if any(base.rsplit(".", 1)[-1] in ("TypedDict", "typing.TypedDict") for base in bases):
+            return "typeddict"
+        return "class"
+
+    def _extract_public_api(
+        self,
+        node: ast.Assign | ast.AnnAssign,
+    ) -> list[str]:
+        """Extract names from __all__ assignment."""
+        target = node.targets[0] if isinstance(node, ast.Assign) else node.target
+        if not (isinstance(target, ast.Name) and target.id == "__all__"):
+            return []
+
+        value = node.value
+        if value is None:
+            return []
+
+        names: list[str] = []
+        if isinstance(value, (ast.List, ast.Tuple)):
+            for elt in value.elts:
+                if isinstance(elt, ast.Constant) and isinstance(elt.value, str):
+                    names.append(elt.value)
+                elif hasattr(ast, "Str") and isinstance(elt, ast.Str):  # noqa: UP023
+                    names.append(str(elt.s))
+        return names

pydoc2markdown/core/watcher.py

@@ -0,0 +1,88 @@
+"""File watcher for auto-regenerating documentation."""
+
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def watch_and_generate(
+    source: Path,
+    output_dir: Path,
+    recursive: bool,
+    theme: str,
+    template_path: Path | None,
+) -> int:
+    """Watch source files and regenerate docs on change.
+
+    Args:
+        source: Path to Python file or directory.
+        output_dir: Output directory for Markdown files.
+        recursive: Whether to scan subdirectories recursively.
+        theme: Built-in theme name.
+        template_path: Optional custom template path.
+
+    Returns:
+        Exit code (0 for success, 1 for error).
+    """
+    try:
+        from watchdog.events import FileSystemEvent, FileSystemEventHandler
+        from watchdog.observers import Observer
+    except ImportError:
+        logger.error(
+            "watchdog is required for --watch. Install it with: pip install pydoc2markdown[watch]"
+        )
+        return 1
+
+    from pydoc2markdown.core.generator import MarkdownGenerator
+    from pydoc2markdown.core.parser import DocstringParser
+
+    generator = MarkdownGenerator(
+        template_path=template_path,
+        theme=theme,
+    )
+
+    class _RebuildHandler(FileSystemEventHandler):
+        def __init__(self) -> None:
+            self._parser = DocstringParser()
+
+        def on_any_event(self, event: FileSystemEvent) -> None:
+            if event.is_directory:
+                return
+            src = getattr(event, "src_path", "")
+            if isinstance(src, str) and not src.endswith(".py"):
+                return
+            logger.info("Change detected, regenerating docs...")
+            try:
+                modules = self._parser.parse(source, recursive=recursive)
+                generator.generate(modules, output_dir)
+                logger.info("Docs regenerated in %s", output_dir)
+            except Exception:
+                logger.exception("Regeneration failed")
+
+    handler = _RebuildHandler()
+    watch_path = source if source.is_dir() else source.parent
+    observer = Observer()
+    observer.schedule(handler, str(watch_path), recursive=True)
+    observer.start()
+
+    logger.info("Watching %s for changes. Press Ctrl+C to stop.", watch_path)
+
+    # Generate once before watching
+    try:
+        modules = handler._parser.parse(source, recursive=recursive)
+        generator.generate(modules, output_dir)
+        logger.info("Initial docs generated in %s", output_dir)
+    except Exception:
+        logger.exception("Initial generation failed")
+
+    try:
+        while observer.is_alive():
+            observer.join(1)
+    except KeyboardInterrupt:
+        logger.info("Stopping watcher...")
+    finally:
+        observer.stop()
+        observer.join()
+
+    return 0

pydoc2markdown/templates/minimal.md

@@ -0,0 +1,31 @@
+# {{ module.name }}
+
+{% if module.docstring %}
+{{ module.docstring }}
+{% endif %}
+
+{% if module.classes %}
+## Classes
+
+{% for class in module.classes %}
+### `{{ class.name }}`{% if class.class_type != "class" %} ({{ class.class_type }}){% endif %}
+
+{% if class.docstring %}
+{{ class.docstring }}
+{% endif %}
+
+{% endfor %}
+{% endif %}
+
+{% if module.functions %}
+## Functions
+
+{% for func in module.functions %}
+### `{{ func.name }}`
+
+{% if func.docstring %}
+{{ func.docstring }}
+{% endif %}
+
+{% endfor %}
+{% endif %}

pydoc2markdown/templates/module.md

@@ -0,0 +1,137 @@
+# {{ module.name }}
+
+{% if module.docstring %}
+{{ module.docstring }}
+{% endif %}
+
+{% if module.classes or module.functions %}
+## Table of Contents
+
+{% if module.classes %}
+- [Classes](#classes)
+{% for class in module.classes %}
+  - [`{{ class.name }}`](#{{ class.name | lower | replace(' ', '-') }})
+{% if class.methods %}
+{% for method in class.methods %}
+    - [
+{% if method.is_property %}@property {% elif method.is_classmethod %}@classmethod
+{% elif method.is_staticmethod %}@staticmethod {% endif %}
+`{{ method.name }}`](#{{ method.name | lower | replace(' ', '-') }})
+{% endfor %}
+{% endif %}
+{% endfor %}
+{% endif %}
+{% if module.functions %}
+- [Functions](#functions)
+{% for func in module.functions %}
+  - [`{{ func.name }}`](#{{ func.name | lower | replace(' ', '-') }})
+{% endfor %}
+{% endif %}
+{% endif %}
+
+{% if module.public_api %}
+**Public API:**
+{% for name in module.public_api %}
+- `{{ name }}`
+{% endfor %}
+{% endif %}
+
+{% if module.classes %}
+## Classes
+
+{% for class in module.classes %}
+### `{{ class.name }}`{% if class.class_type != "class" %} ({{ class.class_type }}){% endif %}
+
+{% if class.bases %}
+**Bases:** `{{ class.bases | join(", ") }}`
+{% endif %}
+
+{% if class.docstring %}
+{{ class.docstring }}
+{% endif %}
+
+{% if class.attributes %}
+#### Attributes
+
+| Name | Type | Description |
+|------|------|-------------|
+{% for attr in class.attributes %}
+| `{{ attr.name }}` | {% if attr.type_hint %}`{{ attr.type_hint }}`{% else %}-{% endif %} | {% if attr.description %}{{ attr.description }}{% else %}-{% endif %} |
+{% endfor %}
+{% endif %}
+
+{% if class.methods %}
+#### Methods
+
+{% for method in class.methods %}
+##### {% if method.is_property %}@property {% elif method.is_classmethod %}@classmethod {% elif method.is_staticmethod %}@staticmethod {% endif %}`{{ method.name }}`
+
+{% if method.docstring %}
+{{ method.docstring }}
+{% endif %}
+
+{% if method.params %}
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+{% for param in method.params %}
+| `{{ param.name }}` | {% if param.type_hint %}`{{ param.type_hint }}`{% else %}-{% endif %} | {% if param.description %}{{ param.description }}{% else %}-{% endif %} |
+{% endfor %}
+{% endif %}
+
+{% if method.returns %}
+**Returns:**{% if method.returns.type_hint %} `{{ method.returns.type_hint }}`{% endif %}
+
+{% if method.returns.description %}{{ method.returns.description }}{% endif %}
+{% endif %}
+
+{% if method.raises %}
+**Raises:**
+{% for raise in method.raises %}
+- {% if raise.type_name %}`{{ raise.type_name }}`{% endif %}{% if raise.description %}: {{ raise.description }}{% endif %}
+{% endfor %}
+{% endif %}
+
+{% endfor %}
+{% endif %}
+
+---
+{% endfor %}
+{% endif %}
+
+{% if module.functions %}
+## Functions
+
+{% for func in module.functions %}
+### `{{ func.name }}`
+
+{% if func.docstring %}
+{{ func.docstring }}
+{% endif %}
+
+{% if func.params %}
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+{% for param in func.params %}
+| `{{ param.name }}` | {% if param.type_hint %}`{{ param.type_hint }}`{% else %}-{% endif %} | {% if param.description %}{{ param.description }}{% else %}-{% endif %} |
+{% endfor %}
+{% endif %}
+
+{% if func.returns %}
+**Returns:**{% if func.returns.type_hint %} `{{ func.returns.type_hint }}`{% endif %}
+
+{% if func.returns.description %}{{ func.returns.description }}{% endif %}
+{% endif %}
+
+{% if func.raises %}
+**Raises:**
+{% for raise in func.raises %}
+- {% if raise.type_name %}`{{ raise.type_name }}`{% endif %}{% if raise.description %}: {{ raise.description }}{% endif %}
+{% endfor %}
+{% endif %}
+
+{% endfor %}
+{% endif %}

pydoc2markdown/utils/__init__.py

@@ -0,0 +1 @@
+"""Utility modules for PyDoc2Markdown."""

pydoc2markdown/utils/helpers.py

@@ -0,0 +1,34 @@
+"""Helper utilities for PyDoc2Markdown."""
+
+import re
+
+
+def clean_docstring(docstring: str | None) -> str | None:
+    """Clean and normalize a docstring."""
+    if not docstring:
+        return None
+    lines = docstring.expandtabs().splitlines()
+    if not lines:
+        return None
+
+    # Find minimum indentation
+    indent = None
+    for line in lines[1:]:
+        stripped = line.lstrip()
+        if stripped:
+            line_indent = len(line) - len(stripped)
+            if indent is None or line_indent < indent:
+                indent = line_indent
+
+    if indent:
+        lines[1:] = [line[indent:] for line in lines[1:]]
+
+    return "\n".join(lines).strip()
+
+
+def slugify(text: str) -> str:
+    """Convert text to a URL-friendly slug."""
+    text = text.lower().strip()
+    text = re.sub(r"[^\w\s-]", "", text)
+    text = re.sub(r"[\s_]+", "-", text)
+    return re.sub(r"-+", "-", text)

pydoc2markdown-0.1.0.dist-info/METADATA

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: pydoc2markdown
+Version: 0.1.0
+Summary: Convert Python docstrings to Markdown documentation.
+Project-URL: Homepage, https://github.com/f1sherFM/PyDoc2Markdown
+Project-URL: Repository, https://github.com/f1sherFM/PyDoc2Markdown
+Project-URL: Issues, https://github.com/f1sherFM/PyDoc2Markdown/issues
+Author-email: f1sherFM <f1sherFM@example.com>
+License: MIT
+License-File: LICENSE
+Keywords: docstring,documentation,markdown,python
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: docstring-parser>=0.15
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: tomli>=1.2.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.5.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.5.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: watchdog>=3.0; extra == 'dev'
+Provides-Extra: watch
+Requires-Dist: watchdog>=3.0; extra == 'watch'
+Description-Content-Type: text/markdown
+
+# PyDoc2Markdown
+
+[![CI](https://github.com/f1sherFM/PyDoc2Markdown/actions/workflows/ci.yml/badge.svg)](https://github.com/f1sherFM/PyDoc2Markdown/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/f1sherFM/PyDoc2Markdown/branch/main/graph/badge.svg)](https://codecov.io/gh/f1sherFM/PyDoc2Markdown)
+[![PyPI](https://img.shields.io/pypi/v/pydoc2markdown)](https://pypi.org/project/pydoc2markdown/)
+
+> Convert Python docstrings into clean, structured Markdown documentation.
+
+## Features
+
+- **Docstring parsing** — Extract Google, NumPy, and reStructuredText style docstrings with structured params, returns, and raises.
+- **Markdown generation** — Produce beautiful Markdown files with customizable Jinja2 templates.
+- **Auto-generated index & TOC** — Each module gets a Table of Contents; an `index.md` with package grouping is created automatically.
+- **Package grouping** — Output files are organized into subdirectories matching the package structure.
+- **Built-in themes** — Choose between `default` (detailed) and `minimal` themes, or supply your own template.
+- **CLI & API** — Use via command line or import as a Python library.
+- **Recursive processing** — Scan entire packages in one command.
+- **Type-aware** — Respects type hints and annotations.
+- **Advanced constructs** — Supports `property`, `classmethod`, `staticmethod`, `dataclass`, `Enum`, `TypedDict`, and `__all__`.
+
+## Installation
+
+```bash
+pip install pydoc2markdown
+```
+
+## Quick Start
+
+### CLI Usage
+
+```bash
+# Generate docs for a single file
+pydoc2markdown my_module.py -o docs
+
+# Recursively process a package
+pydoc2markdown src/my_package --recursive -o docs
+
+# Use a built-in theme
+pydoc2markdown src/my_package --recursive --theme minimal -o docs
+
+# Use a custom template
+pydoc2markdown src/my_package --recursive --template custom.md.j2 -o docs
+
+# Enable verbose logging
+pydoc2markdown src/my_package --recursive -vv -o docs
+```
+
+### Library Usage
+
+```python
+from pathlib import Path
+from pydoc2markdown import DocstringParser, MarkdownGenerator
+
+parser = DocstringParser()
+modules = parser.parse(Path("src/my_package"), recursive=True)
+
+generator = MarkdownGenerator(theme="default")
+generator.generate(modules, output_dir=Path("docs"))
+```
+
+## Documentation
+
+- [Contributing Guide](CONTRIBUTING.md)
+- [Project Structure](PROJECT_STRUCTURE.md)
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.

pydoc2markdown-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+pydoc2markdown/__init__.py,sha256=VFhL3E7U4NYG0gOjsyIfwsFFcu9CezjpqzdSdfB5cbg,511
+pydoc2markdown/cli.py,sha256=00ssjGZDCX6CRiMRqRPZ8IdavwSSpzTFjUcA-TW0YDs,3826
+pydoc2markdown/core/__init__.py,sha256=2L8gqlhFk5aUEdVweMh6n14qBP3otOvaqY9HFzuItZE,37
+pydoc2markdown/core/config.py,sha256=7a4Xkt9V6wSqlZFXcAxt5UE0KvHPtf-dAtcktrEmE20,939
+pydoc2markdown/core/generator.py,sha256=iSROflUXlqjNnCHTLVVe2yyhfD7ciZORN8fs56bCwnc,7979
+pydoc2markdown/core/parser.py,sha256=gYmFR-iHI69I3fEbo-xne249ftI1aExjMG84dXTeobI,13595
+pydoc2markdown/core/watcher.py,sha256=vYGUi6qzXyO0EpHYpZug8fVbOLsyzdRRR-_d71Qnj6U,2774
+pydoc2markdown/templates/minimal.md,sha256=QywFgdjpYOYgKQC_DGiWYXgAiAa_lsq_yj0FSvkWDdY,516
+pydoc2markdown/templates/module.md,sha256=Hkp-vi02pErjhz4V5iodDmWmqXjfJxU15ruuP6Hhruw,3596
+pydoc2markdown/utils/__init__.py,sha256=MCa1nvJ2iCaeED3zbqu3_2rPiUm19biNiFWxPiACyqU,42
+pydoc2markdown/utils/helpers.py,sha256=HMyAr_pJ0Zz2HlqbyBsMTTCIQmVmvXtDM5Gj4lVHU_c,900
+pydoc2markdown-0.1.0.dist-info/METADATA,sha256=6EgH34a8hNuHvM3OGddTMMeA6SP_Ig6z4WG_8UFibn8,3885
+pydoc2markdown-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+pydoc2markdown-0.1.0.dist-info/entry_points.txt,sha256=bfIiW3kqPCQExc2kQREAE2ExHDJ1HMA3x1JP6hXDr1w,59
+pydoc2markdown-0.1.0.dist-info/licenses/LICENSE,sha256=aZoyljz1cF1y9zrTZmigukeEoCIdOoWiQ6P4F7FVSgs,1065
+pydoc2markdown-0.1.0.dist-info/RECORD,,

pydoc2markdown-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pydoc2markdown-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pydoc2markdown = pydoc2markdown.cli:main

pydoc2markdown-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 f1sherFM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.