tessl/pypi-pydoc-markdown

Create Python API documentation in Markdown format

—

Pending

Overview

Eval results

Files

CLI Interface

Name: tessl/pypi-pydoc-markdown
Author: tessl

Comprehensive command-line interface providing extensive options for documentation generation, development servers, project bootstrapping, and workflow automation.

Capabilities

RenderSession Class

Helper class that orchestrates CLI rendering sessions, managing configuration loading, overrides, and execution phases.

class RenderSession:
    """
    Helper class for CLI rendering sessions that handles configuration loading,
    applying overrides, and managing the rendering workflow.
    
    Attributes:
        config: Configuration object or file path
        render_toc: Override render_toc option in MarkdownRenderer  
        search_path: Override search path in Python loader
        modules: Override modules in Python loader
        packages: Override packages in Python loader
        py2: Override Python 2 compatibility in Python loader
    """
    
    def __init__(
        self,
        config: Union[None, dict, str],
        render_toc: Optional[bool] = None,
        search_path: Optional[List[str]] = None,
        modules: Optional[List[str]] = None,
        packages: Optional[List[str]] = None,
        py2: Optional[bool] = None
    ):
        """
        Initialize render session with configuration and overrides.
        
        Args:
            config: Configuration dictionary or path to config file
            render_toc: Override table of contents rendering
            search_path: Override module search paths
            modules: Override specific modules to document
            packages: Override specific packages to document  
            py2: Override Python 2 compatibility mode
        """
    
    def load(self) -> PydocMarkdown:
        """
        Load configuration and apply overrides.
        
        Returns:
            Configured PydocMarkdown instance
        """
    
    def render(self, config: PydocMarkdown) -> List[str]:
        """
        Execute rendering process and return list of files to watch.
        
        Args:
            config: PydocMarkdown configuration
            
        Returns:
            List of file paths that should be watched for changes
        """
    
    def build(self, config: PydocMarkdown, site_dir: str) -> None:
        """
        Execute build process for renderers that support building.
        
        Args:
            config: PydocMarkdown configuration
            site_dir: Directory for build output
        """
    
    def run_server(self, config: PydocMarkdown, open_browser: bool = False):
        """
        Start development server with file watching and auto-reload.
        
        Args:
            config: PydocMarkdown configuration
            open_browser: Whether to automatically open browser
        """

CLI Command Function

Main CLI entry point that handles argument parsing, validation, and execution coordination.

def cli() -> None:
    """
    Main CLI command entry point for pydoc-markdown.
    
    Available as 'pydoc-markdown' command after installation.
    Handles all CLI arguments, validation, and execution coordination.
    """

Utility Functions

def error(*args) -> NoReturn:
    """
    Print error message and exit with status 1.
    
    Args:
        *args: Error message components to print
    """

CLI Usage Examples

Basic Usage

# Generate docs with default configuration
pydoc-markdown

# Generate docs from specific config file
pydoc-markdown pydoc-markdown.yml

# Generate docs from inline YAML
pydoc-markdown '
loaders:
  - type: python
    modules: [mypackage]
renderer:
  type: markdown
  filename: api.md
'

Module and Package Options

# Document specific modules
pydoc-markdown -m mypackage.core -m mypackage.utils

# Document entire packages
pydoc-markdown -p mypackage -p otherpkg

# Document with custom search paths
pydoc-markdown -m mypackage -I src/ -I lib/

# Mix modules and packages
pydoc-markdown -m mypackage.core -p mypackage.plugins

Rendering Options

# Enable table of contents
pydoc-markdown --render-toc

# Disable table of contents  
pydoc-markdown --no-render-toc

# Python 2 compatibility mode
pydoc-markdown --py2 -m legacy_package

# Modern Python 3 mode (default)
pydoc-markdown --py3 -m modern_package

Development Server

# Start development server (MkDocs/Hugo renderers)
pydoc-markdown --server

# Start server and open browser
pydoc-markdown --server --open

# Server with custom configuration
pydoc-markdown -c mkdocs-config.yml --server --open

Building

# Build final output (after rendering)
pydoc-markdown --build

# Build to custom directory
pydoc-markdown --build --site-dir /var/www/docs/

# Cannot use server and build together
# pydoc-markdown --server --build  # ERROR

Project Bootstrapping

# Create basic configuration
pydoc-markdown --bootstrap base

# Create MkDocs configuration
pydoc-markdown --bootstrap mkdocs

# Create Hugo configuration  
pydoc-markdown --bootstrap hugo

# Create Docusaurus configuration
pydoc-markdown --bootstrap docusaurus

# Create Read the Docs configuration
pydoc-markdown --bootstrap readthedocs

Debug and Analysis

# Dump parsed modules as JSON
pydoc-markdown --dump -m mypackage

# Dump without running processors
pydoc-markdown --dump --without-processors -m mypackage

# Dump with processors (default)
pydoc-markdown --dump --with-processors -m mypackage

# Increase verbosity
pydoc-markdown -v   # Info level
pydoc-markdown -vv  # Debug level

# Decrease verbosity
pydoc-markdown -q   # Error level only
pydoc-markdown -qq  # Critical level only

Configuration File Discovery

When no config file is specified, pydoc-markdown searches for configuration files in this order:

pydoc-markdown.yml
pydoc-markdown.yaml
pyproject.toml (looks for [tool.pydoc-markdown] section)

# Uses automatic discovery
pydoc-markdown

# Explicit config file
pydoc-markdown pydoc-markdown.yml
pydoc-markdown custom-config.yaml
pydoc-markdown pyproject.toml

Complete CLI Options

Arguments

config (optional): Configuration file path or inline YAML/JSON

Options

General:

--version: Show version and exit
--verbose, -v: Increase log verbosity (can be repeated: -vv)
--quiet, -q: Decrease log verbosity (can be repeated: -qq)

Module Selection:

--module, -m MODULE: Module to document (can be repeated)
--package, -p PACKAGE: Package to document recursively (can be repeated)
--search-path, -I PATH: Module search directory (can be repeated)
--py2/--py3: Python 2/3 compatibility mode

Rendering:

--render-toc/--no-render-toc: Enable/disable table of contents
--server, -s: Start development server
--open, -o: Open browser with server (requires --server)
--build: Build final output after rendering
--site-dir DIR: Build output directory (requires --build)

Analysis:

--dump: Output parsed modules as JSON
--with-processors/--without-processors: Include/exclude processors (with --dump)

Bootstrapping:

--bootstrap TYPE: Create configuration files
- base: Basic configuration
- mkdocs: MkDocs integration
- hugo: Hugo integration
- docusaurus: Docusaurus integration
- readthedocs: Read the Docs setup

Examples by Use Case

Quick Documentation Generation

# Document current package  
pydoc-markdown -p .

# Document with custom output
pydoc-markdown -p mypackage > api-docs.md

# Document specific modules only
pydoc-markdown -m mypackage.api -m mypackage.client

MkDocs Workflow

# Bootstrap MkDocs configuration
pydoc-markdown --bootstrap mkdocs

# Start development server
pydoc-markdown --server --open

# Build for production
pydoc-markdown --build --site-dir ../docs-site/

Hugo Workflow

# Bootstrap Hugo configuration
pydoc-markdown --bootstrap hugo

# Development with live reload
pydoc-markdown --server

# Production build
pydoc-markdown --build

Debug and Analysis Workflow

# See what modules would be loaded
pydoc-markdown --dump --without-processors -p mypackage

# Analyze processing results
pydoc-markdown --dump -p mypackage | jq '.modules[].name'

# Debug with verbose output
pydoc-markdown -vv -p mypackage

Integration Examples

# CI/CD pipeline
pydoc-markdown --build --site-dir docs/
cp -r docs/ /var/www/html/

# Pre-commit hook
pydoc-markdown --dump > /dev/null || exit 1

# Development workflow with watch
pydoc-markdown --server --open &
# Make code changes...
# Server auto-reloads

Install with Tessl CLI