tessl/pypi-pydoc-markdown

Create Python API documentation in Markdown format

—

Pending

Overview

Eval results

Files

Documentation Rendering

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

Comprehensive rendering capabilities that generate documentation output in various formats including standalone Markdown, MkDocs, Hugo, Docusaurus, and custom Jinja2 templates.

Capabilities

Markdown Rendering

Basic Markdown renderer that generates standalone Markdown files with configurable formatting, table of contents, and source linking.

class MarkdownRenderer(Renderer, SinglePageRenderer, SingleObjectRenderer):
    """
    Basic Markdown renderer for generating standalone documentation files.
    
    Attributes:
        filename: Output filename (default: None for stdout)
        add_source_linker: Include source code links (default: True)  
        add_member_class_prefix: Add class prefix to member names (default: True)
        render_toc: Generate table of contents (default: False)
        toc_maxdepth: Maximum TOC depth (default: 2)
        insert_header_anchors: Add anchor links to headers (default: False)
        header_level_by_type: Header levels for different object types
        code_lang: Language for code blocks (default: "python")
        signature_with_def: Include 'def' keyword in signatures (default: False)
        signature_class_prefix: Include class name in method signatures (default: False)
        signature_function_override: Custom signature formatting function
        signature_code_block: Wrap signatures in code blocks (default: True)
        source_linker: Source linker instance for generating source links
    """
    filename: Optional[str]
    add_source_linker: bool
    add_member_class_prefix: bool
    render_toc: bool
    toc_maxdepth: int
    insert_header_anchors: bool
    header_level_by_type: Dict[str, int]
    code_lang: str
    signature_with_def: bool
    signature_class_prefix: bool
    signature_function_override: Optional[str]
    signature_code_block: bool
    source_linker: Optional[SourceLinker]
    
    def render(self, modules: List[docspec.Module]) -> None:
        """
        Render modules to Markdown format.
        
        Args:
            modules: List of modules to render
        """
    
    def render_single_page(self, fp: TextIO, modules: List[docspec.Module], page_title: Optional[str] = None) -> None:
        """
        Render modules to a single page.
        
        Args:
            fp: File object to write to
            modules: List of modules to render
            page_title: Optional title for the page
        """
    
    def render_object(self, fp: TextIO, obj: docspec.ApiObject, options: Dict[str, Any]) -> None:
        """
        Render a single API object.
        
        Args:
            fp: File object to write to
            obj: API object to render
            options: Rendering options
        """

MkDocs Rendering

MkDocs-specific renderer with development server support, automatic navigation generation, and build integration.

class MkdocsRenderer(Renderer, Server, Builder):
    """
    MkDocs renderer with development server and build capabilities.
    
    Attributes:
        config_file_path: Path to mkdocs.yml config file (default: "mkdocs.yml")
        build_directory: Directory for generated files (default: "docs/")  
        site_dir: Directory for built site (default: "site/")
        markdown: Nested MarkdownRenderer for content generation
    """
    config_file_path: str
    build_directory: str
    site_dir: str
    markdown: MarkdownRenderer
    
    def render(self, modules: List[docspec.Module]) -> None:
        """
        Render modules for MkDocs.
        
        Args:
            modules: List of modules to render
        """
    
    def build(self, site_dir: str) -> None:
        """
        Build MkDocs site.
        
        Args:
            site_dir: Directory for build output
        """
    
    def get_server_url(self) -> str:
        """
        Get development server URL.
        
        Returns:
            URL of the development server
        """
    
    def start_server(self) -> subprocess.Popen:
        """
        Start MkDocs development server.
        
        Returns:
            Process handle for the server
        """

Hugo Rendering

Hugo-specific renderer with development server support, content organization, and build integration.

class HugoRenderer(Renderer, Server, Builder):
    """
    Hugo renderer with development server and build capabilities.
    
    Attributes:
        config_file: Hugo config file name (default: "config.toml")
        build_directory: Directory for content files (default: "content/docs/")
        site_dir: Directory for built site (default: "public/")
        hugo_cmd: Hugo command to use (default: "hugo")
        markdown: Nested MarkdownRenderer for content generation
    """
    config_file: str
    build_directory: str
    site_dir: str
    hugo_cmd: str
    markdown: MarkdownRenderer
    
    def render(self, modules: List[docspec.Module]) -> None:
        """
        Render modules for Hugo.
        
        Args:
            modules: List of modules to render
        """
    
    def build(self, site_dir: str) -> None:
        """
        Build Hugo site.
        
        Args:
            site_dir: Directory for build output
        """
    
    def get_server_url(self) -> str:
        """
        Get development server URL.
        
        Returns:
            URL of the development server
        """
    
    def start_server(self) -> subprocess.Popen:
        """
        Start Hugo development server.
        
        Returns:
            Process handle for the server
        """

Docusaurus Rendering

Docusaurus-specific renderer with automatic sidebar generation and content organization optimized for React-based documentation sites.

class DocusaurusRenderer(Renderer):
    """
    Docusaurus renderer for React-based documentation sites.
    
    Attributes:
        config_file_path: Path to docusaurus.config.js (default: "docusaurus.config.js")
        docs_base_path: Base path for documentation files (default: "docs/")
        sidebar_top_level_label: Label for top-level sidebar section (default: "API")  
        sidebar_top_level_module: Module to use as top-level (default: None)
        markdown: Nested MarkdownRenderer for content generation
    """
    config_file_path: str
    docs_base_path: str
    sidebar_top_level_label: str
    sidebar_top_level_module: Optional[str]
    markdown: MarkdownRenderer
    
    def render(self, modules: List[docspec.Module]) -> None:
        """
        Render modules for Docusaurus.
        
        Args:
            modules: List of modules to render
        """

Jinja2 Rendering

Template-based renderer using Jinja2 for complete customization of documentation output format and structure.

class Jinja2Renderer(Renderer):
    """
    Jinja2 template-based renderer for custom documentation formats.
    
    Attributes:
        loader: Jinja2 loader for template discovery
        context: Additional template context variables
        template: Template name to render
    """
    loader: jinja2.BaseLoader
    context: Dict[str, Any]
    template: str
    
    def render(self, modules: List[docspec.Module]) -> None:
        """
        Render modules using Jinja2 templates.
        
        Args:
            modules: List of modules to render
        """

Usage Examples

Basic Markdown Rendering

from pydoc_markdown import PydocMarkdown
from pydoc_markdown.contrib.renderers.markdown import MarkdownRenderer

# Simple Markdown output
renderer = MarkdownRenderer(
    filename='api-docs.md',
    render_toc=True,
    toc_maxdepth=3
)

config = PydocMarkdown(renderer=renderer)
modules = config.load_modules()
config.process(modules)
config.render(modules)

MkDocs Integration

from pydoc_markdown.contrib.renderers.mkdocs import MkdocsRenderer
from pydoc_markdown.contrib.renderers.markdown import MarkdownRenderer

# MkDocs renderer with custom Markdown settings
renderer = MkdocsRenderer(
    config_file_path='mkdocs.yml',
    build_directory='docs/',
    markdown=MarkdownRenderer(
        render_toc=False,  # MkDocs handles TOC
        insert_header_anchors=True
    )
)

config = PydocMarkdown(renderer=renderer)

Hugo Integration

from pydoc_markdown.contrib.renderers.hugo import HugoRenderer

# Hugo renderer with custom configuration
renderer = HugoRenderer(
    config_file='config.yaml',
    build_directory='content/docs/',
    site_dir='public/',
    hugo_cmd='hugo --minify'
)

config = PydocMarkdown(renderer=renderer)

Development Server

from pydoc_markdown.main import RenderSession

# Start development server (for MkDocs/Hugo renderers)
session = RenderSession(config='pydoc-markdown.yml')
config = session.load()

# This starts the server and watches for changes
session.run_server(config, open_browser=True)

Custom Jinja2 Templates

from pydoc_markdown.contrib.renderers.jinja2 import Jinja2Renderer
import jinja2

# Custom template renderer
renderer = Jinja2Renderer(
    loader=jinja2.FileSystemLoader('templates/'),
    template='custom-api.html',
    context={'project_name': 'My Project', 'version': '1.0.0'}
)

config = PydocMarkdown(renderer=renderer)

Configuration Examples

YAML Configuration

# Basic Markdown renderer
renderer:
  type: markdown
  filename: docs/api.md
  render_toc: true
  toc_maxdepth: 3
  insert_header_anchors: true
  code_lang: python

# MkDocs renderer
renderer:
  type: mkdocs
  config_file_path: mkdocs.yml
  build_directory: docs/
  site_dir: site/
  markdown:
    render_toc: false
    insert_header_anchors: true
    signature_code_block: true

# Hugo renderer  
renderer:
  type: hugo
  config_file: config.toml
  build_directory: content/docs/
  site_dir: public/
  hugo_cmd: hugo --minify
  markdown:
    render_toc: false
    header_level_by_type:
      Module: 1
      Class: 2
      Function: 3

# Docusaurus renderer
renderer:
  type: docusaurus
  docs_base_path: docs/
  sidebar_top_level_label: API Reference
  markdown:
    render_toc: false
    signature_code_block: true

Advanced Markdown Configuration

renderer:
  type: markdown
  filename: api-reference.md
  
  # Content options
  render_toc: true  
  toc_maxdepth: 4
  insert_header_anchors: true
  add_source_linker: true
  add_member_class_prefix: false
  
  # Signature formatting
  signature_with_def: false
  signature_class_prefix: true  
  signature_code_block: true
  code_lang: python
  
  # Header levels for different object types
  header_level_by_type:
    Module: 1
    Class: 2
    Function: 3
    Method: 4
    Variable: 4

Multi-Format Rendering

You can also use multiple renderers by running pydoc-markdown multiple times with different configurations:

# Generate Markdown docs
pydoc-markdown -c pydoc-markdown-md.yml

# Generate MkDocs site  
pydoc-markdown -c pydoc-markdown-mkdocs.yml

# Generate Hugo site
pydoc-markdown -c pydoc-markdown-hugo.yml

Server and Build Integration

Development Workflow

# Start development server (auto-rebuilds on changes)
pydoc-markdown --server

# Open browser automatically
pydoc-markdown --server --open

# Build production site
pydoc-markdown --build

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

Programmatic Server Control

from pydoc_markdown.main import RenderSession

session = RenderSession(config='mkdocs-config.yml')
config = session.load()

# Check if renderer supports server
if hasattr(config.renderer, 'start_server'):
    # Start server process
    process = config.renderer.start_server()
    print(f"Server running at {config.renderer.get_server_url()}")
    
    # Server will run until process is terminated
    process.wait()

Install with Tessl CLI