Metadata-Version: 2.4
Name: blathers
Version: 1.0.0a5
Summary: Ontology documentation & validation CLI — bridges auto-extracted OWL/SHACL definitions with Markdown narrative
Project-URL: Homepage, https://github.com/mapsa/blathers
Project-URL: Documentation, https://github.com/mapsa/blathers#readme
Project-URL: Repository, https://github.com/mapsa/blathers
Project-URL: Issues, https://github.com/mapsa/blathers/issues
Project-URL: Changelog, https://github.com/mapsa/blathers/blob/main/CHANGELOG.md
Author-email: Paola Arce <paola@bigspark.dev>
License: MIT
License-File: LICENSE
Keywords: documentation,ontology,owl,rdf,shacl
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: jinja2>=3.1
Requires-Dist: markdown>=3.5
Requires-Dist: pydantic>=2.5
Requires-Dist: pyshacl>=0.26
Requires-Dist: python-frontmatter>=1.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: rdflib>=7.0
Provides-Extra: dev
Requires-Dist: pytest-tmp-files>=0.0.2; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# Blathers

Ontology documentation & validation CLI -- bridges auto-extracted OWL/SHACL definitions with Markdown narrative.

[![PyPI version](https://img.shields.io/pypi/v/blathers)](https://pypi.org/project/blathers/)
[![Python versions](https://img.shields.io/pypi/pyversions/blathers)](https://pypi.org/project/blathers/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

## Features

- **5 validators** -- SHACL, consistency, completeness, naming conventions, and overlap detection
- **Sidecar Markdown** -- author rich narrative alongside your ontology using YAML frontmatter
- **Static HTML output** -- generates a self-contained documentation site with ReSpec-style layout
- **RDF/OWL extraction** -- parses classes, properties, and named individuals via rdflib
- **Content negotiation** -- generates Apache, nginx, and w3id configuration

## Quick start

```bash
pip install blathers
```

Scaffold a new project:

```bash
blathers init my-ontology
cd my-ontology
```

Validate your ontology:

```bash
blathers validate
```

Build the documentation site:

```bash
blathers build
```

## Configuration

Blathers reads from `blathers.yaml` in your project root:

```yaml
ontology: ontology/my-ontology.ttl
shacl: []
sidecars: sidecars/
figures: figures/
output: dist/

metadata:
  title: "My Ontology"
  version: "1.0.0"
  namespace: "http://example.org/onto#"
  prefix: onto

validation:
  fail_on: error
  rules:
    shacl: true
    consistency: true
    completeness: true
    conventions: true
    overlap: true
```

## Sidecar authoring

Create Markdown files in `sidecars/` with YAML frontmatter to add narrative:

```markdown
---
term: onto:MyClass
section: overview
order: 1
---

Description of MyClass and its role in the ontology.
```

## CLI commands

| Command    | Description                                      |
| ---------- | ------------------------------------------------ |
| `init`     | Scaffold a new ontology project                  |
| `validate` | Run validators against ontology and SHACL shapes |
| `build`    | Generate static HTML documentation site          |
| `fetch`    | Fetch remote ontology imports                    |

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.

## License

[MIT](LICENSE)
