A powerful CLI tool for validating JSON/YAML/TOML configuration files against a schema with clear error messages, and auto-generating human-readable markdown documentation from your schemas.

Features

Multi-format Support: Parse and validate JSON, YAML, and TOML configuration files
Schema Validation: Validate configurations against JSON Schema with detailed, actionable error messages
Auto-generated Documentation: Generate clean markdown documentation from your schemas
Environment Profiles: Built-in development, staging, and production profiles with validation rules
Type Inference: Automatically infer schema from existing configurations
CLI Interface: Easy-to-use commands for validation, documentation, and schema initialization

Installation

# Install from PyPI
pip install confdoc

# Or install with development dependencies
pip install confdoc[dev]

Quick Start

Validate a Configuration File

confdoc validate config.json --schema schema.json

Generate Documentation

confdoc doc schema.json --output CONFIGURATION.md

Initialize a New Schema

# Create a starter schema
confdoc init schema.json

# Or infer schema from existing config
confdoc init schema.json --config config.yaml

Usage

validate Command

Validate a configuration file against a schema:

confdoc validate <config-file> [OPTIONS]

Options:

--schema, -s: Path to schema file (default: schema.json)
--format, -f: Config format: json, yaml, toml, auto (default: auto)
--profile, -p: Profile to apply (development, staging, production)
--output, -o: Output format: text, json (default: text)

Example:

confdoc validate config.yaml --schema schema.json --profile development

doc Command

Generate markdown documentation from a schema:

confdoc doc <schema-file> [OPTIONS]

Options:

--output, -o: Output file path
--title, -t: Document title
--format, -f: Output format (default: markdown)

Example:

confdoc doc schema.json --output docs/configuration.md --title "My App Config"

init Command

Initialize a new schema file:

confdoc init [output-file] [OPTIONS]

Options:

--config, -c: Generate schema from existing config file

Example:

# Create a starter schema
confdoc init

# Infer schema from config
confdoc init schema.json --config config.toml

Examples

Example Configuration (config.json)

{
  "app": {
    "name": "myapp",
    "version": "1.0.0",
    "debug": true
  },
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "mydb"
  }
}

Example Schema (schema.json)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Application Configuration",
  "type": "object",
  "properties": {
    "app": {
      "type": "object",
      "properties": {
        "name": {"type": "string", "description": "Application name"},
        "version": {"type": "string", "description": "Application version"},
        "debug": {"type": "boolean", "description": "Enable debug mode", "default": false}
      },
      "required": ["name"]
    },
    "database": {
      "type": "object",
      "properties": {
        "host": {"type": "string", "description": "Database host"},
        "port": {"type": "integer", "description": "Database port", "minimum": 1, "maximum": 65535},
        "name": {"type": "string", "description": "Database name"}
      }
    }
  },
  "required": ["app", "database"]
}

Schema Reference

ConfDoc uses JSON Schema for validation. Supported keywords:

type: string, integer, number, boolean, object, array, null
required: Array of required property names
properties: Object defining each property's schema
enum: List of allowed values
minimum, maximum: Numeric constraints
minLength, maxLength: String length constraints
pattern: Regular expression pattern
default: Default value for the property
description: Human-readable description

Environment Profiles

ConfDoc includes built-in profiles:

Profile	Description
development	Lenient validation, allows extra properties
staging	Strict validation, no extra properties
production	Strict validation, no extra properties

Configuration

Environment Variables

Variable	Description
`CONFDOC_CONFIG_PATH`	Default config path
`CONFDOC_DEFAULT_SCHEMA`	Default schema file

Programmatic Usage

from confdoc.parsers import ConfigParserFactory
from confdoc.validator import SchemaValidator
from confdoc.docs import DocGenerator

# Parse a config file
factory = ConfigParserFactory()
parser = factory.get_parser_for_file("config.json")
config = parser.parse(content)

# Validate against schema
validator = SchemaValidator()
is_valid, errors = validator.validate(config, schema)

# Generate documentation
doc_gen = DocGenerator()
docs = doc_gen.generate(schema, "My Config")

Development

# Clone the repository
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/confdoc.git
cd confdoc

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=confdoc --cov-report=term-missing

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.