https://github.com/mapsa/blathers
Python CLI for ontology documentation — bridges auto-extracted OWL/SHACL definitions with Markdown narrative, validates, and builds static HTML sites.
https://github.com/mapsa/blathers
cli documentation eu-ai-act knowledge-graph linked-data ontology owl python rdf semantic-web shacl w3c
Last synced: 9 days ago
JSON representation
Python CLI for ontology documentation — bridges auto-extracted OWL/SHACL definitions with Markdown narrative, validates, and builds static HTML sites.
- Host: GitHub
- URL: https://github.com/mapsa/blathers
- Owner: mapsa
- License: mit
- Created: 2026-04-02T06:08:01.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-06T17:18:51.000Z (3 months ago)
- Last Synced: 2026-05-06T02:09:37.254Z (about 2 months ago)
- Topics: cli, documentation, eu-ai-act, knowledge-graph, linked-data, ontology, owl, python, rdf, semantic-web, shacl, w3c
- Language: Python
- Size: 235 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Blathers
Ontology documentation & validation CLI -- bridges auto-extracted OWL/SHACL definitions with Markdown narrative.
[](https://pypi.org/project/blathers/)
[](https://pypi.org/project/blathers/)
[](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)