or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-interface.mddocstring-processing.mddocumentation-rendering.mdindex.mdmain-config.mdplugin-interfaces.mdpython-loading.mdutility-functions.md
tile.json

tessl/pypi-pydoc-markdown

Create Python API documentation in Markdown format

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pydoc-markdown@4.8.x

To install, run

npx @tessl/cli install tessl/pypi-pydoc-markdown@4.8.0

index.mddocs/

Pydoc-Markdown

An extensible framework for generating Python API documentation in Markdown format. Pydoc-markdown parses Python source code using docspec (without executing it), processes docstrings through configurable processors, and renders comprehensive documentation through various output formats including standalone Markdown, MkDocs, Hugo, and Docusaurus.

Package Information

  • Package Name: pydoc-markdown
  • Language: Python
  • Installation: pip install pydoc-markdown
  • Requirements: Python 3.7+

Core Imports

from pydoc_markdown import PydocMarkdown

Common imports for customization:

from pydoc_markdown.contrib.loaders.python import PythonLoader
from pydoc_markdown.contrib.processors.filter import FilterProcessor
from pydoc_markdown.contrib.processors.crossref import CrossrefProcessor
from pydoc_markdown.contrib.renderers.markdown import MarkdownRenderer
from pydoc_markdown.contrib.renderers.mkdocs import MkdocsRenderer

Basic Usage

CLI Usage

# Generate docs with default configuration
pydoc-markdown

# Generate docs for specific modules
pydoc-markdown -m mypackage.module1 -m mypackage.module2

# Generate docs for entire packages
pydoc-markdown -p mypackage

# Start development server (for MkDocs renderer)
pydoc-markdown --server

# Bootstrap configuration files
pydoc-markdown --bootstrap mkdocs

Programmatic Usage

from pydoc_markdown import PydocMarkdown
from pydoc_markdown.contrib.loaders.python import PythonLoader
from pydoc_markdown.contrib.renderers.markdown import MarkdownRenderer

# Create configuration
config = PydocMarkdown(
    loaders=[PythonLoader(modules=['mypackage'])],
    renderer=MarkdownRenderer(filename='api.md')
)

# Generate documentation
modules = config.load_modules()
config.process(modules)
config.render(modules)

Configuration File Usage

Create pydoc-markdown.yml:

loaders:
  - type: python
    modules: [mypackage]
processors:
  - type: filter
  - type: smart
  - type: crossref
renderer:
  type: markdown
  filename: api.md

Then run: pydoc-markdown

Architecture

Pydoc-markdown uses a plugin-based architecture with three main component types:

  • Loaders: Extract API information from source code (Python, etc.)
  • Processors: Transform and enhance docstrings (Google/Sphinx style, cross-references, filtering)
  • Renderers: Generate output in various formats (Markdown, MkDocs, Hugo, Docusaurus)

The framework processes documentation in stages:

  1. Load: Parse source code into docspec.Module objects
  2. Process: Transform docstrings and apply filters
  3. Render: Generate final documentation output

This modular design enables flexible documentation workflows, from simple single-file generation to complex multi-format publishing pipelines integrated with static site generators.

Capabilities

Main Configuration

Core configuration class for orchestrating the documentation generation pipeline, managing loaders, processors, and renderers.

class PydocMarkdown:
    loaders: List[Loader]
    processors: List[Processor]  
    renderer: Renderer
    hooks: Hooks
    
    def load_config(self, arg: Union[str, dict]) -> None: ...
    def load_modules(self) -> List[docspec.Module]: ...
    def process(self, modules: List[docspec.Module]) -> None: ...
    def render(self, modules: List[docspec.Module], run_hooks: bool = True) -> None: ...
    def build(self, site_dir: str) -> None: ...

Main Configuration

Python Source Loading

Load and parse Python source code into docspec objects for documentation generation, with support for module discovery, package analysis, and various parsing options.

class PythonLoader(Loader):
    modules: List[str]
    packages: List[str]
    search_path: List[str]
    ignore_when_discovered: List[str]
    parser: docspec_python.Parser
    
    def load(self) -> Iterable[docspec.Module]: ...

Python Loading

Docstring Processing

Transform and enhance docstrings through configurable processors including filtering, smart formatting, cross-reference resolution, and conversion from various documentation styles.

class FilterProcessor(Processor):
    expression: Optional[str]
    documented_only: bool
    do_not_filter_modules: bool
    skip_empty_modules: bool
    
class CrossrefProcessor(Processor):
    loader: Optional[str]
    safe_mode: bool
    
class GoogleProcessor(Processor): ...
class SphinxProcessor(Processor): ...
class SmartProcessor(Processor): ...
class PydocmdProcessor(Processor): ...

Docstring Processing

Documentation Rendering

Generate documentation output in various formats including standalone Markdown, MkDocs, Hugo, Docusaurus, and custom Jinja2 templates.

class MarkdownRenderer(Renderer, SinglePageRenderer, SingleObjectRenderer):
    filename: Optional[str]
    render_toc: bool
    insert_header_anchors: bool
    code_lang: str
    
class MkdocsRenderer(Renderer, Server, Builder):
    config_file_path: str
    build_directory: str
    site_dir: str
    
class HugoRenderer(Renderer, Server, Builder):
    config_file: str
    build_directory: str
    site_dir: str
    hugo_cmd: str

Documentation Rendering

CLI Interface

Command-line interface providing comprehensive options for documentation generation, development servers, and project bootstrapping.

class RenderSession:
    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
    ): ...
    
    def load(self) -> PydocMarkdown: ...
    def render(self, config: PydocMarkdown) -> List[str]: ...
    def build(self, config: PydocMarkdown, site_dir: str) -> None: ...
    def run_server(self, config: PydocMarkdown, open_browser: bool = False): ...

def cli() -> None: ...

CLI Interface

Plugin Interfaces

Abstract interfaces defining the plugin architecture for loaders, processors, renderers, and additional functionality like source linking and development servers.

class Context:
    directory: str

class Loader(PluginBase):
    def load(self) -> Iterable[docspec.Module]: ...

class Processor(PluginBase):
    def process(self, modules: List[docspec.Module], resolver: Optional[Resolver]) -> None: ...

class Renderer(PluginBase):
    def render(self, modules: List[docspec.Module]) -> None: ...
    def get_resolver(self, modules: List[docspec.Module]) -> Optional[Resolver]: ...

class SourceLinker(PluginBase):
    def get_source_url(self, obj: docspec.ApiObject) -> Optional[str]: ...

Plugin Interfaces

Utility Functions

Helper functions and classes for common operations including docspec manipulation, template processing, file watching, and page management.

def get_members_of_type(objs: Union[docspec.ApiObject, List[docspec.ApiObject]], type_: Type[T]) -> List[T]: ...
def format_function_signature(func: docspec.Function, exclude_self: bool = False) -> str: ...
def is_function(obj: docspec.ApiObject) -> TypeGuard[docspec.Function]: ...
def is_method(obj: docspec.ApiObject) -> TypeGuard[docspec.Function]: ...
def watch_paths(paths: List[str]) -> Tuple[Observer, Event]: ...

class Attributor:
    def __init__(self, data: Dict[str, Any]): ...
    def __getattr__(self, name: str) -> Any: ...

Utility Functions

Types

class Hooks:
    pre_render: List[str]
    post_render: List[str]

class LoaderError(Exception): ...

class Resolver(ABC):
    def resolve_ref(self, scope: docspec.ApiObject, ref: str) -> Optional[str]: ...

class ResolverV2(ABC):
    def resolve_reference(self, suite: ApiSuite, scope: docspec.ApiObject, ref: str) -> Optional[docspec.ApiObject]: ...

class SinglePageRenderer(PluginBase):
    def render_single_page(self, fp: TextIO, modules: List[docspec.Module], page_title: Optional[str] = None) -> None: ...

class SingleObjectRenderer(PluginBase):
    def render_object(self, fp: TextIO, obj: docspec.ApiObject, options: Dict[str, Any]) -> None: ...

class Server(ABC):
    def get_server_url(self) -> str: ...
    def start_server(self) -> subprocess.Popen: ...
    def reload_server(self, process: subprocess.Popen) -> subprocess.Popen: ...

class Builder(ABC):
    def build(self, site_dir: str) -> None: ...