Metadata-Version: 2.4
Name: specmd
Version: 0.1.0
Summary: Parse Markdown model definitions into RDF, diagrams, and docs.
Author-email: Arthit Suriyawongkul <suriyawa@tcd.ie>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: Markdown,specification
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Documentation
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.11
Requires-Dist: jinja2
Requires-Dist: pyyaml
Requires-Dist: rdflib
Requires-Dist: rfc8785
Description-Content-Type: text/markdown

# specmd

Parse Markdown model definitions into RDF, diagrams, and docs.

## Functionality

specmd always reads and validates the complete model directory.
It can then generate one or more of the following outputs:

| Format | Description |
| - | - |
| `jsondump` | JSON dump of the parsed model |
| `mkdocs` | MkDocs source files for website generation |
| `plantuml` | PlantUML diagram source |
| `rdf` | OWL+SHACL ontology and JSON-LD context |
| `tex` | TeX source for printable specification |
| `singlefile` | Single Markdown file (Pandoc → Word) |
| `webpages` | Per-IRI web pages *(not yet implemented)* |

## Installation

```shell
pip install specmd
```

## Usage

specmd uses subcommands:

```text
specmd <command> [options]

Commands:
  generate (gen)   Generate output artefacts from a model directory
  validate         Validate a model directory without generating output
  migrate          Convert spec-parser format to specmd format
  export           Export a specmd model to another format
```

### Validate

Check that a model directory is correctly formatted:

```shell
specmd validate path/to/model
```

### Generate

Generate all output formats into subdirectories under `./out/`:

```shell
specmd generate path/to/model --output ./out
```

Generate specific formats only:

```shell
specmd generate path/to/model --formats rdf,mkdocs --output ./out
```

Override the output directory for a single format:

```shell
specmd generate path/to/model --output ./out --rdf-dir ./ontology
```

Available formats:
`jsondump`, `mkdocs`, `plantuml`, `rdf`, `tex`, `singlefile`, `webpages`.

### Migrate

Convert a model written in the spec-parser format to specmd format:

```shell
specmd migrate path/to/old-model --output path/to/new-model
```

### Export

Export a specmd model back to the spec-parser format:

```shell
specmd export path/to/model --output path/to/exported --format legacy
```

### Common options

| Option | Commands | Description |
| - | - | - |
| `-o`/`--output DIR` | `generate`, `migrate`, `export` | Output directory |
| `-f`/`--force` | `generate`, `migrate`, `export` | Overwrite existing output |
| `-q`/`--quiet` | all | Warnings and errors only |
| `-v`/`--verbose` | all | Debug output |
| `-V`/`--version` | top-level | Show version and exit |

Full help:

```shell
specmd --help
specmd generate --help
```

## Prerequisites

All Python dependencies are installed automatically with `pip install specmd`.
External tools required for specific formats:

| Format | External prerequisite |
| - | - |
| `tex` | [pandoc](https://pandoc.org/) |
| `singlefile` | [pandoc](https://pandoc.org/) |
| All others | None |

## spec-parser compatibility

A `main.py` compatibility shim is provided for existing CI/scripts that
invoke the [spdx/spec-parser] CLI.

It accepts spec-parser's original command-line arguments, internally runs
`specmd migrate` on the input, then `specmd generate` or `specmd validate`.

Simply replace `python spec-parser/main.py` with `python specmd/main.py` in
existing workflows.

## History

specmd is built on the design of [spdx/spec-parser], with a goal of being
a drop-in replacement. Several features originate from proposals that were
filed as issues or submitted as pull requests there but never merged.

The Markdown input format is nearly identical, with the following changes:

- **Front matter** is now a standard `---`-delimited YAML block.
  spec-parser used a bare `SPDX-License-Identifier:` line before the first
  heading -- non-standard Markdown and flagged by markdownlint.
- **Section headings** are read case-insensitively; specmd normalises them at
  parse time. spec-parser required exact Title Case.
- **Properties section** format changed: spec-parser used a bare `- propName`
  entry followed by a `- type: ...` sub-line;
  specmd uses `- propName:` (trailing colon, no `type:` line).
  Aligned with YAML format (allowed us to use PyYAML to handle this without
  the need of custom parser) and less typing/less error-prone.
- **Format section** values are now backtick-wrapped
  (e.g. `` - pattern: `regex` ``), to allow correct display in Markdown
  (e.g. when review it on GitHub "preview" view).
- **Metadata keys** are now camelCase (e.g. `subClassOf`) instead of Title Case
  or custom casing (e.g. `SubclassOf`), aligning with standard vocabulary terms
  such as `rdfs:subClassOf`.
- **Instantiability** field replaced: spec-parser used
  `- Instantiability: Abstract`; specmd uses `- abstract: true`.
- **Deprecation** information (`deprecated`, `deprecatedVersion`,
  `isReplacedBy`) moved from inline bold prose in the Description section to
  structured metadata fields, with corresponding RDF/OWL predicates.
- **Vocabulary entries** support a structured format with `from`, `to`, and
  `relationshipClass` sub-fields for relationship type vocabularies,
  extracted automatically from prose descriptions during migration.
  This information enables SHACL validation rules and enables specialised
  rendering of relationship types on the specification website (future work).
- **New metadata fields**: `example` and `sinceVersion` are supported across
  all element types.

Models written in the original spec-parser format
(such as [spdx/spdx-3-model](https://github.com/spdx/spdx-3-model))
can be converted to specmd format using `specmd migrate`.
specmd models can be converted back using `specmd export --format legacy`.

[spdx/spec-parser]: https://github.com/spdx/spec-parser/
