tessl/pypi-pelican

Static site generator supporting Markdown and reStructuredText

—

Pending

Overview

Eval results

Files

Main Application

Name: tessl/pypi-pelican
Author: tessl

Core Pelican application class and entry points for static site generation, providing the main orchestration logic, configuration management, and command-line interface.

Capabilities

Pelican Class

Main application class that coordinates the site generation process, managing generators, plugins, and output writing.

class Pelican:
    """
    Main Pelican application class for static site generation.
    
    Parameters:
    - settings (dict): Configuration dictionary containing all site settings
    """
    def __init__(self, settings: dict): ...
    
    def run(self) -> None:
        """
        Execute the complete site generation process.
        
        Runs all generators, processes content, applies themes, and writes output files.
        """
    
    def init_path(self) -> None:
        """Initialize Python path for plugin and content discovery."""
    
    def init_plugins(self) -> None:
        """Load and register enabled plugins."""
    
    # Instance attributes available after initialization
    settings: dict             # Site configuration
    path: str                 # Content source path
    theme: str                # Theme path
    output_path: str          # Output directory path
    plugins: list             # Loaded plugin instances
    ignore_files: list        # Files to ignore during processing
    delete_outputdir: bool    # Whether to clean output directory before generation
    output_retention: list    # Files to retain when cleaning output directory

CLI Entry Points

Main command-line interface functions for running Pelican from the command line.

def main(argv=None) -> None:
    """
    Main CLI entry point for the pelican command.
    
    Parameters:
    - argv (optional): Command line arguments (defaults to sys.argv)
    """

def parse_arguments(argv=None):
    """
    Parse command-line arguments and return argument namespace.
    
    Parameters:
    - argv (optional): Command line arguments to parse
    
    Returns:
    argparse.Namespace: Parsed arguments
    """

Configuration Management

Functions for building configuration from command-line arguments and creating Pelican instances.

def get_config(args) -> dict:
    """
    Build configuration dictionary from parsed command-line arguments.
    
    Parameters:
    - args: Parsed argument namespace from parse_arguments()
    
    Returns:
    dict: Configuration dictionary for Pelican initialization
    """

def get_instance(args) -> tuple[Pelican, dict]:
    """
    Create Pelican instance and settings from command-line arguments.
    
    Parameters:
    - args: Parsed argument namespace from parse_arguments()
    
    Returns:
    tuple: (Pelican instance, settings dictionary)
    """

Development Features

Functions for development workflow including auto-reload and HTTP server functionality.

def autoreload(args, excqueue=None) -> None:
    """
    Run Pelican in auto-reload mode, regenerating on file changes.
    
    Parameters:
    - args: Parsed argument namespace
    - excqueue (multiprocessing.Queue, optional): Exception queue for multiprocessing
    """

def listen(server: str, port: int, output: str, excqueue=None) -> None:
    """
    Start HTTP development server for generated site.
    
    Parameters:
    - server (str): Server bind address (e.g., '127.0.0.1')
    - port (int): Server port number
    - output (str): Output directory path to serve
    - excqueue (multiprocessing.Queue, optional): Exception queue for multiprocessing
    """

Command-Line Options

The main pelican command supports these key options:

path: Content source directory (positional argument)
-o, --output: Output directory path
-s, --settings: Settings file path (defaults to pelicanconf.py)
-t, --theme-path: Theme directory path
-d, --delete-output-directory: Clean output directory before generation
-r, --autoreload: Enable auto-reload on content changes
-l, --listen: Start development HTTP server
-p, --port: HTTP server port (default: 8000)
-v, --verbose: Verbose output
-q, --quiet: Quiet output (errors only)
-D, --debug: Debug output
--relative-urls: Use relative URLs for development
--cache-path: Cache directory path
--ignore-cache: Ignore existing cache
-e, --extra-settings: Override settings (KEY=VALUE format)

Usage Examples

Basic Site Generation

from pelican import Pelican
from pelican.settings import read_settings

# Load settings from file
settings = read_settings('pelicanconf.py')

# Create and run Pelican instance
pelican_instance = Pelican(settings)
pelican_instance.run()

Programmatic Configuration

from pelican import Pelican
from pelican.settings import DEFAULT_CONFIG

# Create custom settings
settings = DEFAULT_CONFIG.copy()
settings.update({
    'PATH': 'content',
    'OUTPUT_PATH': 'output',
    'SITENAME': 'My Blog',
    'SITEURL': 'https://example.com'
})

# Generate site
pelican_instance = Pelican(settings)
pelican_instance.run()

Development Workflow

from pelican import parse_arguments, get_instance, autoreload, listen
import multiprocessing

# Parse command-line arguments
args = parse_arguments(['content', '--autoreload', '--listen'])

# Run with auto-reload and development server
if args.autoreload and args.listen:
    pelican_instance, settings = get_instance(args)
    excqueue = multiprocessing.Queue()
    
    p1 = multiprocessing.Process(target=autoreload, args=(args, excqueue))
    p2 = multiprocessing.Process(
        target=listen, 
        args=(settings.get('BIND'), settings.get('PORT'), settings.get('OUTPUT_PATH'), excqueue)
    )
    
    p1.start()
    p2.start()

Install with Tessl CLI