rstcheck

A comprehensive Python CLI tool for checking the syntax of reStructuredText files and code blocks nested within them. rstcheck validates both the RST document structure and the syntax of embedded code blocks in multiple programming languages, making it essential for documentation quality assurance in Python projects and technical writing workflows.

Package Information

• Package Name: rstcheck
• Package Type: pypi
• Language: Python
• Installation: pip install rstcheck

Optional extras:

• pip install rstcheck[toml] - TOML configuration support
• pip install rstcheck[sphinx] - Sphinx directive/role support

Core Imports

The primary interface is the command-line tool, but programmatic access is available:

from rstcheck import _cli

Basic Usage

Command Line Interface

Basic syntax checking:

# Check a single RST file
rstcheck document.rst

# Check multiple files
rstcheck doc1.rst doc2.rst src/readme.rst

# Check all RST files in a directory recursively
rstcheck --recursive docs/

# Read from stdin
cat document.rst | rstcheck -

Configuration Examples

Using command-line options:

# Ignore specific code block languages
rstcheck --ignore-languages cpp,javascript document.rst

# Set report level
rstcheck --report-level ERROR --log-level INFO document.rst

# Use custom config file
rstcheck --config myproject.cfg document.rst

# Ignore custom directives and roles
rstcheck --ignore-directives custom-directive --ignore-roles custom-role document.rst

Using configuration file (.rstcheck.cfg or pyproject.toml):

[rstcheck]
ignore_directives = custom-directive,foobar
ignore_roles = custom-role
ignore_messages = (Title underline too short\.$)
ignore_languages = cpp,javascript
report_level = warning

Capabilities

File Processing

Core file processing functionality for RST syntax validation.

# Command: rstcheck [OPTIONS] FILES...
# FILES: One or more RST file paths, directories (with --recursive), or "-" for stdin

File Input Options:

• Multiple file paths: Check specific RST files
• Directory with --recursive: Recursively find and check all .rst files
• Stdin with "-": Read RST content from standard input (exclusive with other files)

Configuration Management

Configuration system supporting multiple file formats and sources.

# Configuration options
--config PATH          # Config file or directory path
--warn-unknown-settings # Log warnings for unknown config settings

Configuration File Resolution:

1. Path specified via --config option
2. .rstcheck.cfg in current or parent directories
3. pyproject.toml with [tool.rstcheck] section (requires toml extra)
4. setup.cfg with [rstcheck] section

Supported Configuration Formats:

• INI format (.cfg, .ini files): [rstcheck] section
• TOML format (pyproject.toml): [tool.rstcheck] section

Report Level Control

Control the severity level of issues reported.

--report-level LEVEL   # Report level: INFO|WARNING|ERROR|SEVERE|NONE
--log-level LEVEL     # Application log level: DEBUG|INFO|WARNING|ERROR|CRITICAL

Report Levels:

• INFO: Report all issues including informational messages
• WARNING: Report warnings and above (default)
• ERROR: Report errors and severe issues only
• SEVERE: Report only severe structural issues
• NONE: Suppress all issue reporting (exit code still reflects status)

Content Filtering

Flexible filtering system to ignore specific RST elements and code blocks.

--ignore-directives TEXT    # Comma-separated directives to ignore
--ignore-roles TEXT         # Comma-separated roles to ignore
--ignore-substitutions TEXT # Comma-separated substitutions to ignore
--ignore-languages TEXT     # Comma-separated code block languages to ignore
--ignore-messages REGEX     # Regular expression for messages to ignore

Ignore Options:

• Directives: Skip validation of custom or problematic RST directives
• Roles: Skip validation of custom or problematic RST roles
• Substitutions: Skip validation of undefined substitution references
• Languages: Skip syntax checking of code blocks in specified languages
• Messages: Skip issues matching the provided regular expression pattern

Directory Processing

Recursive directory processing with flexible file discovery.

--recursive, -r        # Recursively search directories for RST files

Directory Processing Features:

• Automatic .rst file discovery in directory trees
• Configurable file filtering via configuration
• Preserves directory structure in error reporting

Code Block Validation

Comprehensive syntax validation for embedded code blocks in multiple languages.

Supported Languages:

• Bash: Shell script syntax validation
• Doctest: Python doctest format validation
• C: C99 standard syntax checking
• C++: C++11 standard syntax checking
• JSON: JSON format validation
• XML: XML structure and syntax validation
• Python: Python syntax checking
• reStructuredText: Nested RST content validation

Version Information

Version reporting for rstcheck and its dependencies.

--version              # Print version information and exit

Version Output:

• rstcheck CLI version
• rstcheck-core library version
• Enabled feature information (Sphinx, TOML support)

Programmatic Interface

While primarily a CLI tool, programmatic access is available for integration.

from rstcheck._cli import main, setup_logger, cli

def main() -> None:
    """Run the CLI application."""
    # Entry point for programmatic execution

def setup_logger(loglevel: str) -> None:
    """Set up logging configuration.
    
    Args:
        loglevel (str): Logging level (DEBUG|INFO|WARNING|ERROR|CRITICAL)
        
    Raises:
        TypeError: On invalid logging levels
    """

def cli(
    files: list[pathlib.Path],
    config: pathlib.Path | None = None,
    warn_unknown_settings: bool | None = None,
    recursive: bool | None = None,
    report_level: str | None = None,
    log_level: str = "WARNING",
    ignore_directives: str | None = None,
    ignore_roles: str | None = None,
    ignore_substitutions: str | None = None,
    ignore_languages: str | None = None,
    ignore_messages: str | None = None,
    version: bool | None = None,
) -> None:
    """Main CLI function with full parameter control.
    
    Args:
        files: List of RST file paths to check
        config: Path to configuration file or directory
        warn_unknown_settings: Log warnings for unknown config settings
        recursive: Recursively search directories for RST files
        report_level: Issue report level (INFO|WARNING|ERROR|SEVERE|NONE)
        log_level: Application logging level
        ignore_directives: Comma-separated directives to ignore
        ignore_roles: Comma-separated roles to ignore
        ignore_substitutions: Comma-separated substitutions to ignore
        ignore_languages: Comma-separated languages to ignore in code blocks
        ignore_messages: Regular expression for messages to ignore
        version: Print version information and exit
    
    Raises:
        typer.Exit: On completion (with appropriate exit code)
        FileNotFoundError: When specified config path is not found
    """

Error Handling

rstcheck provides comprehensive error reporting with structured output.

Exit Codes:

• 0: Success, no issues detected
• 1: Issues detected or execution error

Error Message Format:

filename.rst:line: (SEVERITY/level) message context

Common Error Categories:

• RST Structure: Title underlines, section hierarchy, directive syntax
• Code Block Syntax: Language-specific syntax errors in embedded code
• Reference Errors: Undefined links, substitutions, or cross-references
• Configuration Errors: Invalid settings or missing config files

Error Suppression:

• Global suppression via --report-level NONE
• Selective suppression via ignore options
• Pattern-based suppression via --ignore-messages
• Inline suppression via RST comments (when supported by rstcheck-core)

Integration

Pre-commit Hook

rstcheck includes pre-commit hook configuration:

repos:
  - repo: https://github.com/rstcheck/rstcheck
    rev: v6.2.5
    hooks:
      - id: rstcheck
        additional_dependencies: [rstcheck[sphinx,toml]]

CI/CD Integration

Command-line interface enables easy CI/CD integration:

# Fail build on any RST issues
rstcheck --report-level ERROR docs/

# Check all documentation with custom config
rstcheck --recursive --config .rstcheck.cfg docs/

Development Workflow

Integration with development tools and workflows:

• tox: Multi-environment testing with RST validation
• pre-commit: Automatic RST checking on commit
• GitHub Actions: Automated documentation validation
• Sphinx: Documentation build pipeline integration

Dependencies

Required Dependencies:

• rstcheck-core >=1.1: Core RST checking functionality
• typer >=0.12.0: Modern CLI framework

Optional Dependencies:

• sphinx >=6.0: Sphinx directive and role support
• tomli >=2.0 (Python ≤3.10): TOML configuration file support

Performance Considerations

• File Processing: Efficient batch processing of multiple files
• Directory Scanning: Optimized recursive directory traversal
• Memory Usage: Streaming file processing for large documents
• Parallel Processing: Single-threaded but optimized for CI/CD pipelines

Advanced Configuration

Custom Directive Support

Configure rstcheck to recognize project-specific RST extensions:

[rstcheck]
ignore_directives = 
    custom-directive,
    project-specific-directive,
    legacy-directive
ignore_roles = 
    custom-role,
    domain-specific-role

Language-Specific Settings

Fine-tune code block validation for your project's needs:

[rstcheck]
# Skip validation for languages not relevant to your project
ignore_languages = cpp,rust,go
# Focus on critical languages
report_level = ERROR

Message Filtering

Use regular expressions to suppress specific known issues:

[rstcheck]
# Suppress title underline warnings for specific patterns
ignore_messages = (Title underline too short for title.*\.$)|(Unknown directive type.*\.$)