Command Line Interface

def cli(args: list[str] | None = None) -> None:
    """
    Command-line interface entry point.
    
    Parameters:
    - args: list[str] | None - Command line arguments (uses sys.argv if None)
    
    Features:
    - Argument parsing and validation
    - Rendering configuration
    - Output directory or web server mode
    - Error handling and user feedback
    """

def get_dev_version() -> str:
    """
    Return detailed version string with git information for development builds.
    
    Returns:
    - str: Version string with git commit hash if available
    """

# Generate documentation for a module
pdoc my_module

# Generate documentation for a Python file
pdoc ./my_script.py

# Generate documentation for multiple modules
pdoc module1 module2 module3

# Exclude submodules using negative patterns
pdoc my_package !my_package.internal

# Save documentation to HTML files
pdoc my_module -o ./docs

# Save to specific directory with custom name
pdoc my_module --output-directory ./api-docs

# Generate documentation without starting web server
pdoc my_module -o ./output

# Start development server (default: localhost:8080)
pdoc my_module

# Custom host and port
pdoc my_module --host 0.0.0.0 --port 3000

# Bind to all interfaces
pdoc my_module --host 0.0.0.0

# Use Google-style docstring format
pdoc my_module --docformat google

# Use NumPy-style docstring format  
pdoc my_module --docformat numpy

# Use reStructuredText format (default)
pdoc my_module --docformat restructuredtext

# Use plain Markdown
pdoc my_module --docformat markdown

# Include undocumented members
pdoc my_module --include-undocumented

# Hide undocumented members
pdoc my_module --no-include-undocumented

# Show source code links
pdoc my_module --show-source

# Hide source code links
pdoc my_module --no-show-source

# Enable math formula rendering
pdoc my_module --math

# Enable Mermaid diagram rendering
pdoc my_module --mermaid

# Disable search functionality
pdoc my_module --no-search

# Use custom template directory
pdoc my_module --template-directory ./custom_templates

# Add project logo
pdoc my_module --logo "https://example.com/logo.png"

# Logo with custom link
pdoc my_module --logo "logo.png" --logo-link "https://example.com"

# Custom favicon
pdoc my_module --favicon "favicon.ico"

# Custom footer text
pdoc my_module --footer-text "© 2024 My Project"

# Add edit links to GitHub
pdoc my_module --edit-url my_module=https://github.com/user/repo/blob/main/my_module/

# Multiple edit URL mappings
pdoc my_module other_module \
  --edit-url my_module=https://github.com/user/repo1/blob/main/my_module/ \
  --edit-url other_module=https://github.com/user/repo2/blob/main/other_module/

# Show version information
pdoc --version

# Show help message
pdoc --help

# Show detailed help for all options
pdoc -h

#!/bin/bash
# Generate production documentation

pdoc my_package \
  --output-directory ./docs \
  --docformat google \
  --no-show-source \
  --logo "https://my-site.com/logo.png" \
  --logo-link "https://my-site.com" \
  --footer-text "© 2024 My Company" \
  --favicon "https://my-site.com/favicon.ico" \
  --edit-url my_package=https://github.com/mycompany/my_package/blob/main/my_package/

pdoc my_package \
  --host localhost \
  --port 8080 \
  --docformat google \
  --show-source \
  --math \
  --mermaid \
  --template-directory ./dev_templates \
  --logo "./assets/dev-logo.png"

# Document multiple related packages together
pdoc core_package utils_package plugins_package \
  --output-directory ./complete_docs \
  --docformat numpy \
  --math \
  --edit-url core_package=https://github.com/org/core/blob/main/core_package/ \
  --edit-url utils_package=https://github.com/org/utils/blob/main/utils_package/ \
  --edit-url plugins_package=https://github.com/org/plugins/blob/main/plugins_package/

# Serve with custom templates for development
pdoc my_package \
  --template-directory ./custom_templates \
  --host localhost \
  --port 3000 \
  --show-source \
  --footer-text "Custom Template Development"

#!/bin/bash
# CI script for documentation generation

set -e

echo "Generating API documentation..."

pdoc my_package \
  --output-directory ./dist/docs \
  --docformat google \
  --no-show-source \
  --logo "$LOGO_URL" \
  --logo-link "$PROJECT_URL" \
  --footer-text "Built on $(date)" \
  --edit-url my_package="$REPO_URL/blob/$BRANCH_NAME/my_package/"

echo "Documentation generated successfully!"

# Generate with maximum verbosity for debugging
pdoc my_module \
  --include-undocumented \
  --show-source \
  --docformat restructuredtext \
  --template-directory ./debug_templates

# Test different docstring formats
pdoc my_module --docformat google    # Test Google style
pdoc my_module --docformat numpy     # Test NumPy style  
pdoc my_module --docformat markdown  # Test Markdown

# Makefile targets for documentation

.PHONY: docs docs-serve docs-clean

docs:
	pdoc my_package -o ./docs --docformat google --logo ./assets/logo.png

docs-serve:
	pdoc my_package --host localhost --port 8080 --docformat google --show-source

docs-clean:
	rm -rf ./docs

{
  "scripts": {
    "docs": "pdoc my_package -o ./docs --docformat google",
    "docs:serve": "pdoc my_package --host localhost --port 8080",
    "docs:clean": "rm -rf ./docs"
  }
}

name: Generate Documentation

on:
  push:
    branches: [ main ]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
          
      - name: Install dependencies
        run: |
          pip install pdoc
          pip install -e .
          
      - name: Generate documentation
        run: |
          pdoc my_package \
            --output-directory ./docs \
            --docformat google \
            --logo "https://my-site.com/logo.png" \
            --edit-url my_package=https://github.com/${{ github.repository }}/blob/main/my_package/
            
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs

# Make sure module is installed or use file path
pdoc ./path/to/module.py

# Install missing dependencies first
pip install -r requirements.txt
pdoc my_module

# Check template directory exists and is readable
pdoc my_module --template-directory ./templates

# Use different port or let pdoc choose automatically
pdoc my_module --port 0  # Auto-select available port