Documentation Maintenance Toolkit API

For Developers:

This module provides a unified, comprehensive system for documentation maintenance, quality checking, and building operations. It consolidates functionality from multiple scripts into a single, well-structured Python tool.

Overview

The Documentation Maintenance Toolkit is a consolidation of three separate scripts:

check_docs_style.sh - Style compliance checking
check_documentation_quality.py - Comprehensive quality analysis
doc_maintenance_commands.sh - Build and utility functions

This unified approach eliminates code duplication, provides consistent error handling, and offers a more maintainable codebase.

Quick Start

Basic usage examples:

# Style compliance check (fast - for pre-commit hooks)
python scripts/utils/doc_maintenance_toolkit.py --mode style

# Comprehensive quality analysis
python scripts/utils/doc_maintenance_toolkit.py --mode quality

# Build documentation
python scripts/utils/doc_maintenance_toolkit.py --mode build

# Full maintenance suite
python scripts/utils/doc_maintenance_toolkit.py --mode full

Migration from Old Scripts

This toolkit consolidates three previously separate scripts. If you were using the old scripts, here’s how to migrate:

Command Equivalents

Style Checking:

# Old
bash scripts/utils/check_docs_style.sh

# New
python3 scripts/utils/doc_maintenance_toolkit.py --mode style

Quality Checking:

# Old
python3 scripts/utils/check_documentation_quality.py

# New
python3 scripts/utils/doc_maintenance_toolkit.py --mode quality

Build Documentation:

# Old
bash scripts/utils/doc_maintenance_commands.sh build

# New
python3 scripts/utils/doc_maintenance_toolkit.py --mode build

Full Maintenance:

# Old (run all scripts separately)
bash scripts/utils/check_docs_style.sh
python3 scripts/utils/check_documentation_quality.py
bash scripts/utils/doc_maintenance_commands.sh build

# New (single command)
python3 scripts/utils/doc_maintenance_toolkit.py --mode full

Key Improvements

Unified Interface: One command instead of three separate scripts
Consistent Logging: All logs centralized in .logs/ directory
Better Error Handling: Robust Python error handling vs shell scripts
Type Safety: Type hints for improved code quality
Enhanced Options: More control with --quick, --quiet, --verbose
Exit Codes: Standardized exit codes (0=success, 1=warnings, 2=errors)
Maintainability: Single codebase easier to enhance and debug

Backward Compatibility

Note

Old scripts are archived in scripts/utils/archived_*/ for reference and emergency rollback. They are no longer actively maintained.

All functionality from the old scripts has been preserved in the new toolkit. No breaking changes have been introduced.

Common Migration Scenarios

Pre-Commit Hooks:

# Update your .git/hooks/pre-commit
# Old
bash scripts/utils/check_docs_style.sh || exit 1

# New
python3 scripts/utils/doc_maintenance_toolkit.py --mode style || exit 1

CI/CD Pipelines:

# Update your .github/workflows/*.yml
# Old
- name: Check documentation quality
  run: python3 scripts/utils/check_documentation_quality.py

# New
- name: Check documentation quality
  run: python3 scripts/utils/doc_maintenance_toolkit.py --mode quality

Makefile Targets:

# Update your Makefile
# Old
docs-quality:
    @python3 scripts/utils/check_documentation_quality.py

# New
docs-quality:
    @python3 scripts/utils/doc_maintenance_toolkit.py --mode quality

Troubleshooting Migration

Import Errors:: The new toolkit properly handles the logging module import to avoid shadowing issues. If you encounter import errors, ensure you’re using Python 3.7+.
Different Output Format:: The output format is functionally identical but may have minor cosmetic differences (file paths shown as basenames, alphabetical sorting). These are intentional improvements for cleaner output.
Log Location:: All logs now go to .logs/ directory by default. Update any scripts that parse log files to use the new location.
Exit Codes:: Exit codes are now standardized: 0 (success), 1 (warnings), 2 (errors). Update any automation that relies on specific exit codes.

Operation Modes

The toolkit supports four primary operation modes:

style: Quick style compliance check. Verifies that documentation follows project style guidelines including required headers and technical jargon detection. Ideal for pre-commit hooks.
quality: Comprehensive quality analysis. Performs deep analysis including version reference checking, file size analysis, redundancy detection, and cross-reference validation. Recommended for quarterly maintenance.
build: Build Sphinx documentation. Compiles HTML documentation with proper error handling and verification. Optionally opens in browser.
full: Complete maintenance suite. Runs all checks and builds documentation. Provides comprehensive quality report.

Command-Line Options

--mode {style,quality,build,full}: Required. Operation mode to execute.

--quick: Run only basic checks. Faster execution for pre-commit scenarios. Primarily affects quality mode.

--quiet: Suppress non-error output. Useful for CI/CD integration.

--verbose: Provide detailed output. Helpful for debugging and understanding what checks are being performed.

--open: Open documentation in browser after successful build. Only applicable with --mode build.

--version: Display version information and exit.

Exit Codes

The toolkit uses standard exit codes for integration with CI/CD pipelines:

Code	Meaning
0	Success - all checks passed
1	Warnings - non-critical issues found
2	Errors - critical issues that must be fixed

Logging

All operations are logged to the .logs/ directory with detailed timestamp, level, and message information:

Log File	Contents
`doc_style_check.log`	Style mode operation logs
`doc_quality_check.log`	Quality mode operation logs
`doc_build.log`	Build mode operation logs
`doc_full_maintenance.log`	Full maintenance mode logs

Log Format

All log entries follow this format:

YYYY-MM-DD HH:MM:SS - logger_name - LEVEL - message

Example:

2025-10-30 14:23:45 - doc_maintenance - INFO - Documentation style check started

Module Structure

The toolkit is organized into several key classes:

Classes

Colors

class scripts.utils.doc_maintenance_toolkit.Colors[source]

Bases: object

ANSI color codes for terminal output.

Provides the same color-coded output as the original bash scripts for consistency and user familiarity.

Terminal color formatting utilities for consistent, readable output.

Provides ANSI color codes matching the original bash scripts for user familiarity and visual consistency.

Example Usage:

print(Colors.green("Success!"))
print(Colors.red("Error occurred"))
print(Colors.yellow("Warning: Check this"))

BLUE = '\x1b[0;34m'

GREEN = '\x1b[0;32m'

NC = '\x1b[0m'

RED = '\x1b[0;31m'

YELLOW = '\x1b[1;33m'

static blue(text)[source]

Return text in blue color.

Return type:: str

static green(text)[source]

Return text in green color.

Return type:: str

static red(text)[source]

Return text in red color.

Return type:: str

static yellow(text)[source]

Return text in yellow color.

Return type:: str

QualityIssue

class scripts.utils.doc_maintenance_toolkit.QualityIssue(severity, category, file_path, line_number, message)[source]

Bases: object

Represents a documentation quality issue.

severity: Issue severity level (‘info’, ‘warning’, ‘error’)

category: Issue category (e.g., ‘style_compliance’, ‘version_reference’)

file_path: Relative path to the file with the issue

line_number: Line number where issue occurs (0 if not applicable)

message: Human-readable description of the issue

Data class representing a documentation quality issue.

Attributes:

severity: str: Issue severity level: ‘info’, ‘warning’, or ‘error’

category: str: Issue category (e.g., ‘style_compliance’, ‘version_reference’)

file_path: str: Relative path to file containing the issue

line_number: int: Line number where issue occurs (0 if not applicable)

message: str: Human-readable description of the issue

category: str

file_path: str

line_number: int

message: str

severity: str

MaintenanceLogger

class scripts.utils.doc_maintenance_toolkit.MaintenanceLogger(repo_root)[source]

Bases: object

Centralized logging system for all maintenance operations.

Provides consistent logging across all maintenance operations with proper file handling, formatting, and log rotation support.

All logs are saved to the .logs/ directory in the repository root.

log_dir: Path to the .logs directory

_loggers: Cache of created logger instances

Centralized logging system for all maintenance operations.

Provides consistent logging with proper file handling, formatting, and separation of concerns. All logs are written to the .logs/ directory.

Example Usage:

logger_system = MaintenanceLogger(repo_root)
logger = logger_system.get_logger('my_operation', 'custom.log')
logger.info("Operation started")
logger.error("Something went wrong")

__init__(repo_root)[source]

Initialize the logging system.

Parameters:: repo_root (Path) – Path to repository root directory

get_logger(name, log_file=None)[source]

Get or create a logger for a specific operation.

Parameters:

name (str) – Logger name (typically module or operation name)
log_file (Optional[str]) – Optional specific log file name (defaults to name.log)

Return type:

Logger

Returns:

Configured logger instance

StyleChecker

class scripts.utils.doc_maintenance_toolkit.StyleChecker(docs_root, logger, quiet=False)[source]

Bases: object

Documentation style compliance checker.

Checks documentation files for compliance with the project’s style guide: - User guide files must start with “For Users:” - Developer guide files must start with “For Developers:” - User guide files should not contain technical jargon - Sphinx builds must complete without warnings or errors

This class replicates functionality from check_docs_style.sh.

Documentation style compliance checker.

Verifies that documentation follows project style guidelines:

User guide files start with “For Users:”
Developer guide files start with “For Developers:”
User guide avoids technical jargon
Sphinx builds complete without warnings

Example Usage:

checker = StyleChecker(docs_root, logger, quiet=False)
exit_code = checker.run_all_checks()
if exit_code == 0:
    print("All style checks passed!")

__init__(docs_root, logger, quiet=False)[source]

Initialize the style checker.

Parameters:

docs_root (Path) – Path to docs/sphinx directory
logger (Logger) – Logger instance for this checker
quiet (bool) – If True, suppress non-error output

check_developer_guide_headers()[source]

Check developer guide files for required headers.

Return type:: List[str]
Returns:: List of files missing the required header

check_sphinx_build()[source]

Run Sphinx build and check for warnings/errors.

Return type:: Tuple[int, str]
Returns:: Tuple of (exit_code, output)

check_technical_jargon()[source]

Check user guide for technical jargon.

Return type:: Dict[str, List[str]]
Returns:: Dictionary mapping file names to list of found jargon terms

check_user_guide_headers()[source]

Check user guide files for required headers.

Return type:: List[str]
Returns:: List of files missing the required header

run_all_checks()[source]

Run all style compliance checks.

Return type:: int
Returns:: Exit code (0=success, 1=failure)

QualityChecker

class scripts.utils.doc_maintenance_toolkit.QualityChecker(docs_root, logger, quick_mode=False, verbose=False)[source]

Bases: object

Comprehensive documentation quality analyzer.

Performs deep analysis of documentation quality including: - Outdated version references - File size analysis - Redundant content detection - Broken cross-references - Outdated date references

This class replicates and enhances functionality from check_documentation_quality.py.

Comprehensive documentation quality analyzer.

Performs deep analysis of documentation quality:

Outdated version references
File size analysis (warns if >1000 lines)
Redundant content detection
Broken cross-references
Outdated date references

Example Usage:

checker = QualityChecker(docs_root, logger, quick_mode=False)
exit_code = checker.run_all_checks()
# Detailed report printed to console

__init__(docs_root, logger, quick_mode=False, verbose=False)[source]

Initialize the quality checker.

Parameters:

docs_root (Path) – Path to docs/sphinx directory
logger (Logger) – Logger instance for this checker
quick_mode (bool) – If True, run only basic checks
verbose (bool) – If True, provide detailed output

add_issue(severity, category, file_path, line_number, message)[source]

Add a quality issue to the tracking list.

Parameters:

severity (str) – Issue severity (‘info’, ‘warning’, ‘error’)
category (str) – Issue category
file_path (str) – File where issue was found
line_number (int) – Line number (0 if not applicable)
message (str) – Description of the issue

Return type:

None

check_broken_references()[source]

Check for potentially broken cross-references.

Return type:: None

check_file_sizes()[source]

Check for files exceeding size recommendations.

Return type:: None

check_outdated_dates()[source]

Check for potentially outdated date references.

Return type:: None

check_redundant_content()[source]

Check for potential redundant content across files.

Return type:: None

check_style_compliance()[source]

Check for style compliance issues.

Verifies that documentation files have the required headers: - User guide files must start with “For Users:” - Developer guide files must start with “For Developers:”

This check ensures consistency with the project’s documentation style guide and matches the original check_documentation_quality.py behavior.

Return type:: None

check_version_references()[source]

Check for outdated version references.

Return type:: None

generate_report()[source]

Generate and print the quality check report.

Return type:: int
Returns:: Exit code (0=success, 1=warnings, 2=errors)

run_all_checks()[source]

Run all quality checks.

Return type:: int
Returns:: Exit code (0=success, 1=warnings, 2=errors)

DocumentationBuilder

class scripts.utils.doc_maintenance_toolkit.DocumentationBuilder(docs_root, logger, quiet=False)[source]

Bases: object

Documentation building and verification system.

Handles Sphinx documentation building with proper error handling and verification. Supports clean builds, incremental builds, and opening built documentation in the browser.

This class replicates functionality from doc_maintenance_commands.sh.

Documentation building and verification system.

Handles Sphinx documentation building with:

Clean builds (make clean && make html)
Incremental builds
Browser integration
Comprehensive error handling

Example Usage:

builder = DocumentationBuilder(docs_root, logger)
success = builder.build_docs(clean=True)
if success:
    builder.open_docs()

__init__(docs_root, logger, quiet=False)[source]

Initialize the documentation builder.

Parameters:

docs_root (Path) – Path to docs/sphinx directory
logger (Logger) – Logger instance for this builder
quiet (bool) – If True, suppress non-error output

build_docs(clean=True)[source]

Build Sphinx documentation.

Parameters:: clean (bool) – If True, run ‘make clean’ before building
Return type:: bool
Returns:: True if build succeeded, False otherwise

open_docs()[source]

Open built documentation in the default browser.

Return type:: bool
Returns:: True if successful, False otherwise

MaintenanceRunner

class scripts.utils.doc_maintenance_toolkit.MaintenanceRunner(repo_root, args)[source]

Bases: object

Main orchestrator for all documentation maintenance operations.

Coordinates all maintenance tools and provides a unified interface for running different maintenance modes.

Main orchestrator for all maintenance operations.

Coordinates all maintenance tools and provides unified interface for running different modes. Handles logging setup, mode execution, and result reporting.

Example Usage:

args = parse_arguments()
runner = MaintenanceRunner(repo_root, args)
exit_code = runner.run_full_maintenance()

__init__(repo_root, args)[source]

Initialize the maintenance runner.

Parameters:

repo_root (Path) – Path to repository root
args (Namespace) – Parsed command-line arguments

run_build()[source]

Run documentation build.

Return type:: int
Returns:: Exit code

run_full_maintenance()[source]

Run full maintenance suite.

Return type:: int
Returns:: Exit code (worst of all checks)

run_quality_check()[source]

Run comprehensive quality check.

Return type:: int
Returns:: Exit code

run_style_check()[source]

Run style compliance check.

Return type:: int
Returns:: Exit code

Functions

parse_arguments

scripts.utils.doc_maintenance_toolkit.parse_arguments()[source]

Parse command-line arguments.

Return type:: Namespace
Returns:: Parsed arguments

Parse and validate command-line arguments.

Returns:: argparse.Namespace: Parsed arguments with validated values
Raises:: SystemExit: If invalid arguments provided

main

scripts.utils.doc_maintenance_toolkit.main()[source]

Main entry point.

Return type:: int
Returns:: Exit code

Main entry point for the toolkit.

Coordinates argument parsing, validation, and execution of the requested maintenance mode.

Returns:: int: Exit code (0=success, 1=warnings, 2=errors)

Example:

When run as a script:

if __name__ == '__main__':
    sys.exit(main())

Security Considerations

The toolkit implements several security best practices:

Input Validation: All file paths are validated before use. No arbitrary paths accepted.
Safe Subprocess Execution: All subprocess calls use timeouts and capture output safely. No shell injection vulnerabilities.
Logging Security: Logs written only to controlled .logs/ directory. No sensitive data logged.
Error Handling: Comprehensive error handling prevents information leakage. All exceptions logged appropriately.

Migration from Old Scripts

If you’re migrating from the old separate scripts, here’s the mapping:

From `check_docs_style.sh`

# Old way
./scripts/utils/check_docs_style.sh

# New way
python scripts/utils/doc_maintenance_toolkit.py --mode style

From `check_documentation_quality.py`

# Old way
python scripts/utils/check_documentation_quality.py

# New way
python scripts/utils/doc_maintenance_toolkit.py --mode quality

From `doc_maintenance_commands.sh`

# Old way (sourcing and calling function)
source scripts/utils/doc_maintenance_commands.sh
doc_build

# New way
python scripts/utils/doc_maintenance_toolkit.py --mode build

Full Maintenance

# Old way (manual)
./scripts/utils/check_docs_style.sh
python scripts/utils/check_documentation_quality.py
source scripts/utils/doc_maintenance_commands.sh && doc_build

# New way (one command)
python scripts/utils/doc_maintenance_toolkit.py --mode full

Troubleshooting

Script Won’t Execute

Ensure the script is executable:

chmod +x scripts/utils/doc_maintenance_toolkit.py

Check Python version (requires 3.6+):

python3 --version

Import Errors

Run from repository root:

cd /path/to/RePORTaLiN
python3 scripts/utils/doc_maintenance_toolkit.py --mode style

Verify __version__.py exists:

ls -la __version__.py

Logs Not Created

Check .logs directory exists:

ls -la .logs/

Create if missing:

mkdir -p .logs

Ensure write permissions:

chmod 755 .logs

Sphinx Build Fails

Verify Sphinx is installed:

pip list | grep -i sphinx

Check make is available:

which make

Verify docs directory structure:

ls -la docs/sphinx/

Performance Notes

The toolkit is optimized for different use cases:

Quick Checks (Pre-Commit): Use --mode style --quick for fastest execution. Typical runtime: 2-5 seconds.
Comprehensive Analysis: Use --mode quality for thorough checking. Typical runtime: 10-30 seconds depending on doc size.
Full Maintenance: Use --mode full for complete verification. Typical runtime: 30-60 seconds including build.
CI/CD Integration: Use --quiet flag to reduce output noise. Exit codes enable proper pipeline integration.

Version History

Added in version 1.0.0: Initial consolidated release combining three separate scripts.

Note

This tool replaces check_docs_style.sh, check_documentation_quality.py, and doc_maintenance_commands.sh. The old scripts are archived but available in tmp/backups_*/ for reference.

Documentation Maintenance Toolkit API

Overview

Quick Start

Migration from Old Scripts

Command Equivalents

Key Improvements

Backward Compatibility

Common Migration Scenarios

Troubleshooting Migration

Operation Modes

Command-Line Options

Exit Codes

Logging

Log Format

Module Structure

Classes

Colors

QualityIssue

MaintenanceLogger

StyleChecker

QualityChecker

DocumentationBuilder

MaintenanceRunner

Functions

parse_arguments

main

Security Considerations

Migration from Old Scripts

From check_docs_style.sh

From check_documentation_quality.py

From doc_maintenance_commands.sh

Full Maintenance

Troubleshooting

Script Won’t Execute

Import Errors

Logs Not Created

Sphinx Build Fails

Performance Notes

Related Documentation

Version History

See Also

From `check_docs_style.sh`

From `check_documentation_quality.py`

From `doc_maintenance_commands.sh`