tessl/pypi-pydoc-markdown

Create Python API documentation in Markdown format

—

Pending

Overview

Eval results

Files

Python Loading

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

Python source code loading capabilities that parse Python modules and packages into docspec objects for documentation generation.

Capabilities

PythonLoader

Loads Python source code using docspec_python, providing comprehensive module discovery, package analysis, and configurable parsing options.

class PythonLoader(Loader):
    """
    Loader implementation that parses Python modules and packages using docspec_python.
    
    With no modules or packages set, discovers available modules in current and src/ directories.
    
    Attributes:
        modules: List of module names to load (e.g., ["mypackage.module1"])
        packages: List of package names to load recursively (e.g., ["mypackage"])
        search_path: List of directories to search for modules (defaults to current and src/)
        ignore_when_discovered: List of module/package names to ignore during discovery
        parser: docspec_python.Parser instance with parsing configuration
    """
    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]:
        """
        Load and parse Python modules into docspec objects.
        
        Returns:
            Iterable of docspec.Module objects containing parsed API information
            
        Raises:
            LoaderError: If module loading or parsing fails
        """

Parser Configuration

The parser field provides access to docspec_python.Parser configuration options for controlling how Python code is parsed.

# Common parser configuration options accessed via loader.parser:
# parser.print_function: bool - Enable Python 3 print function syntax (default: True)
# parser.encoding: str - Source file encoding (default: "utf-8")
# parser.treat_singleline_comment_blocks_as_docstrings: bool - Treat comment blocks as docstrings

Usage Examples

Basic Module Loading

from pydoc_markdown import PydocMarkdown
from pydoc_markdown.contrib.loaders.python import PythonLoader

# Load specific modules
loader = PythonLoader(
    modules=['mypackage.core', 'mypackage.utils']
)

config = PydocMarkdown(loaders=[loader])
modules = config.load_modules()

Package Loading

from pydoc_markdown.contrib.loaders.python import PythonLoader

# Load entire packages recursively
loader = PythonLoader(
    packages=['mypackage', 'mypackage.subpackage']
)

config = PydocMarkdown(loaders=[loader])
modules = config.load_modules()

Custom Search Path

from pydoc_markdown.contrib.loaders.python import PythonLoader

# Load with custom search paths
loader = PythonLoader(
    modules=['mypackage'],
    search_path=['src/', 'lib/', '/opt/custom/python/']
)

config = PydocMarkdown(loaders=[loader])
modules = config.load_modules()

Module Discovery with Filtering

from pydoc_markdown.contrib.loaders.python import PythonLoader

# Auto-discover modules but ignore specific ones
loader = PythonLoader(
    # Leave modules and packages empty for auto-discovery
    ignore_when_discovered=['test_*', 'internal', 'deprecated_module']
)

config = PydocMarkdown(loaders=[loader])
modules = config.load_modules()

Parser Configuration

from pydoc_markdown.contrib.loaders.python import PythonLoader
import docspec_python

# Configure parser for Python 2 compatibility
loader = PythonLoader(
    modules=['legacy_package'],
    parser=docspec_python.Parser(print_function=False)  # Python 2 print statement
)

# Or modify existing parser
loader = PythonLoader(modules=['mypackage'])
loader.parser.treat_singleline_comment_blocks_as_docstrings = True
loader.parser.encoding = 'latin-1'

Configuration Examples

YAML Configuration

loaders:
  - type: python
    modules:
      - mypackage.core
      - mypackage.utils
    packages:
      - mypackage.subpackage
    search_path:
      - src/
      - lib/
    ignore_when_discovered:
      - test_*
      - internal.*

Comprehensive Configuration

loaders:
  - type: python
    # Specific modules to document
    modules:
      - mypackage.api
      - mypackage.client
    
    # Packages to document recursively  
    packages:
      - mypackage.core
      - mypackage.plugins
    
    # Custom search directories
    search_path:
      - src/
      - vendor/
      - /opt/myproject/
    
    # Modules to ignore during auto-discovery
    ignore_when_discovered:
      - test_*
      - *_test
      - internal
      - deprecated.*
      - experimental.*

Multiple Loaders

loaders:
  # Main package loader
  - type: python
    packages: [mypackage]
    search_path: [src/]
    
  # Separate loader for plugin system
  - type: python  
    modules: [myplugins.core]
    search_path: [plugins/]
    
  # Legacy code with Python 2 syntax
  - type: python
    modules: [legacy]
    search_path: [legacy/]

Module Discovery Behavior

When neither modules nor packages are specified, PythonLoader automatically discovers available modules:

Current Directory: Searches for Python files and packages in the current working directory
src/ Directory: If present, searches the src/ directory for Python packages
Filtering: Applies ignore_when_discovered patterns to exclude unwanted modules
Recursive: Discovers packages recursively, including all submodules and subpackages

Discovery Examples

# Project structure:
# myproject/
#   ├── src/
#   │   └── mypackage/
#   │       ├── __init__.py
#   │       ├── core.py
#   │       └── utils.py
#   ├── tests/
#   └── setup.py

# Auto-discovery will find:
# - mypackage (from src/)
# - mypackage.core
# - mypackage.utils

loader = PythonLoader()  # No modules/packages specified
modules = loader.load()  # Discovers src/mypackage/ automatically

Install with Tessl CLI