7000pctAUTO/confdoc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

fix: resolve CI/CD workflow issues
Some checks failed
CI / test (push) Has been cancelled
Details
CI / lint (push) Has been cancelled
Details
CI / build (push) Has been cancelled
Details

Browse Source
This commit is contained in:
7000pctAUTO
2026-01-31 07:35:35 +00:00
parent 99116a8df2
commit f881168b7d
1 changed files with 133 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files

251
README.md
View File

@@ -1,24 +1,25 @@
# ConfDoc - Configuration Validation and Documentation Generator # 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. A CLI tool that validates JSON/YAML/TOML configuration files against a schema and auto-generates human-readable documentation. It provides schema validation with clear error messages and generates markdown documentation from the schema itself, solving configuration management challenges for developers and DevOps teams.
## Features ## Features
- **Multi-format Support**: Parse and validate JSON, YAML, and TOML configuration files - **Multi-format Support**: Parse and validate JSON, YAML, and TOML configuration files
- **Schema Validation**: Validate configurations against JSON Schema with detailed, actionable error messages - **Schema Validation**: Validate configs against JSON Schema with detailed, actionable error messages
- **Auto-generated Documentation**: Generate clean markdown documentation from your schemas - **Documentation Generation**: Auto-generate markdown documentation from your schemas
- **Environment Profiles**: Built-in development, staging, and production profiles with validation rules - **Environment Profiles**: Built-in development, staging, and production profiles
- **Type Inference**: Automatically infer schema from existing configurations - **Type Checking**: Extract and validate types from schemas with default values
- **CLI Interface**: Easy-to-use commands for validation, documentation, and schema initialization
## Installation ## Installation
```bash ```bash
# Install from PyPI
pip install confdoc pip install confdoc
```
# Or install with development dependencies Or from source:
pip install confdoc[dev]
```bash
pip install -e .
``` ```
## Quick Start ## Quick Start
@@ -26,87 +27,80 @@ pip install confdoc[dev]
### Validate a Configuration File ### Validate a Configuration File
```bash ```bash
# Validate a config file against a schema
confdoc validate config.json --schema schema.json confdoc validate config.json --schema schema.json
# Specify format explicitly
confdoc validate config.yaml --schema schema.json --format yaml
# Apply a profile
confdoc validate config.json --schema schema.json --profile production
# JSON output
confdoc validate config.json --schema schema.json --output json
``` ```
### Generate Documentation ### Generate Documentation
```bash ```bash
confdoc doc schema.json --output CONFIGURATION.md # Generate documentation from a schema
confdoc doc schema.json
# Write to a file
confdoc doc schema.json --output CONFIG.md
# Custom title
confdoc doc schema.json --title "My App Configuration"
``` ```
### Initialize a New Schema ### Initialize a Schema
```bash ```bash
# Create a starter schema # Create a starter schema
confdoc init schema.json confdoc init schema.json
# Or infer schema from existing config # Generate schema from existing config
confdoc init schema.json --config config.yaml confdoc init schema.json --config config.json
``` ```
## Usage ## Usage
### validate Command ### Commands
Validate a configuration file against a schema: | Command | Description |
|---------|-------------|
| `confdoc validate <config>` | Validate a configuration file |
| `confdoc doc <schema>` | Generate documentation from schema |
| `confdoc init [output]` | Initialize a new schema file |
```bash ### Options
confdoc validate <config-file> [OPTIONS]
```
Options: #### Validate Command
- `--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: | Option | Description |
```bash |--------|-------------|
confdoc validate config.yaml --schema schema.json --profile development | `--schema, -s` | Path to schema file (default: schema.json) |
``` | `--format, -f` | Config format: json, yaml, toml, auto |
| `--profile, -p` | Profile to apply: development, staging, production |
| `--output, -o` | Output format: text, json |
### doc Command #### Doc Command
Generate markdown documentation from a schema: | Option | Description |
|--------|-------------|
| `--output, -o` | Output file path |
| `--title, -t` | Document title |
| `--format, -f` | Output format (default: markdown) |
```bash #### Init Command
confdoc doc <schema-file> [OPTIONS]
```
Options: | Option | Description |
- `--output, -o`: Output file path |--------|-------------|
- `--title, -t`: Document title | `--config, -c` | Generate schema from existing config file |
- `--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 ## Examples
### Example Configuration (config.json) ### Example Configuration (JSON)
```json ```json
{ {
@@ -123,7 +117,7 @@ confdoc init schema.json --config config.toml
} }
``` ```
### Example Schema (schema.json) ### Example Schema
```json ```json
{ {
@@ -135,47 +129,32 @@ confdoc init schema.json --config config.toml
"type": "object", "type": "object",
"properties": { "properties": {
"name": {"type": "string", "description": "Application name"}, "name": {"type": "string", "description": "Application name"},
"version": {"type": "string", "description": "Application version"}, "version": {"type": "string", "description": "Version"},
"debug": {"type": "boolean", "description": "Enable debug mode", "default": false} "debug": {"type": "boolean", "description": "Debug mode", "default": false}
}, },
"required": ["name"] "required": ["name"]
}, },
"database": { "database": {
"type": "object", "type": "object",
"properties": { "properties": {
"host": {"type": "string", "description": "Database host"}, "host": {"type": "string"},
"port": {"type": "integer", "description": "Database port", "minimum": 1, "maximum": 65535}, "port": {"type": "integer", "minimum": 1, "maximum": 65535}
"name": {"type": "string", "description": "Database name"}
} }
} }
}, },
"required": ["app", "database"] "required": ["app"]
} }
``` ```
## Schema Reference ### Error Output
ConfDoc uses JSON Schema for validation. Supported keywords: When validation fails, ConfDoc provides clear, actionable error messages:
- `type`: string, integer, number, boolean, object, array, null ```
- `required`: Array of required property names ✗ Configuration validation failed
- `properties`: Object defining each property's schema - 'port' is not of type 'string' in app.database
- `enum`: List of allowed values → Expected type string, but got integer.
- `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 ## Configuration
@@ -186,48 +165,84 @@ ConfDoc includes built-in profiles:
| `CONFDOC_CONFIG_PATH` | Default config path | | `CONFDOC_CONFIG_PATH` | Default config path |
| `CONFDOC_DEFAULT_SCHEMA` | Default schema file | | `CONFDOC_DEFAULT_SCHEMA` | Default schema file |
### Programmatic Usage ### Configuration Files
ConfDoc looks for configuration in:
1. `confdoc.yaml`
2. `.confdocrc`
3. `pyproject.toml` section `[tool.confdoc]`
## Profiles
ConfDoc includes built-in profiles for different environments:
### Development
- Relaxed validation (additionalProperties allowed)
- Debug mode enabled by default
- DEBUG log level
### Staging
- Strict validation
- Debug disabled
- INFO log level
### Production
- Strict validation
- Debug disabled
- WARNING log level
Create custom profiles:
```python ```python
from confdoc.parsers import ConfigParserFactory from confdoc.profiles import ProfileManager
from confdoc.validator import SchemaValidator
from confdoc.docs import DocGenerator
# Parse a config file manager = ProfileManager()
factory = ConfigParserFactory() manager.save_profile("custom", {
parser = factory.get_parser_for_file("config.json") "name": "Custom",
config = parser.parse(content) "validation": {"strict": True},
"overrides": {"custom_key": "value"}
# 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 ## Schema Reference
ConfDoc supports JSON Schema draft-07 with these commonly used keywords:
| Keyword | Description |
|---------|-------------|
| `type` | Value type (string, integer, boolean, object, array) |
| `required` | Array of required property names |
| `properties` | Object property definitions |
| `description` | Property description for docs |
| `default` | Default value |
| `enum` | Allowed values |
| `minimum` | Minimum value (numbers) |
| `maximum` | Maximum value (numbers) |
| `minLength` | Minimum string length |
| `maxLength` | Maximum string length |
| `pattern` | Regex pattern |
## Testing
```bash ```bash
# Clone the repository # Run all tests
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/confdoc.git
cd confdoc
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest tests/ -v pytest tests/ -v
# Run with coverage # Run with coverage
pytest tests/ --cov=confdoc --cov-report=term-missing pytest tests/ --cov=src/confdoc --cov-report=term-missing
# Run specific test file
pytest tests/test_parsers.py -v
``` ```
## Contributing ## Contributing
Contributions are welcome! Please feel free to submit a Pull Request. 1. Fork the repository
2. Create a feature branch
3. Add your changes
4. Write tests
5. Submit a pull request
## License ## License
This project is licensed under the MIT License - see the LICENSE file for details. MIT License - see [LICENSE](LICENSE) file for details.