confdoc/README.md

# ConfDoc - Configuration Validation and Documentation Generator

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

```bash
# Install from PyPI
pip install confdoc

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

## Quick Start

### Validate a Configuration File

```bash
confdoc validate config.json --schema schema.json
```

### Generate Documentation

```bash
confdoc doc schema.json --output CONFIGURATION.md
```

### Initialize a New Schema

```bash
# 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:

```bash
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:
```bash
confdoc validate config.yaml --schema schema.json --profile development
```

### doc Command

Generate markdown documentation from a schema:

```bash
confdoc doc <schema-file> [OPTIONS]
```

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

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

### init Command

Initialize a new schema file:

```bash
confdoc init [output-file] [OPTIONS]
```

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

Example:
```bash
# Create a starter schema
confdoc init

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

## Examples

### Example Configuration (config.json)

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

### Example Schema (schema.json)

```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

```python
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

```bash
# 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.