ttl2mkdocs — Website generation for ISO 14812¶

This directory contains the Python toolchain that builds the MkDocs site (term pages, group/pattern pages, concept diagrams, and navigation) from the modular Turtle ontology in docs/.

The main entry point is ttl2mkdocs.py. Supporting modules:

Module	Role
`ontology_processor_ttl.py`	Discover modules, load the unified graph, registries, clause validation
`markdown_generator.py`	Term/group/pattern/index Markdown and `mkdocs.yml` nav updates
`diagram_generator.py`	Graphviz DOT / SVG / PNG concept diagrams
`utils.py`	Labels, breadcrumbs, page-feedback links, helpers
`split_ontology.py`	Utility for splitting / linkifying ontology content
`fields.py`	Shared field helpers

These scripts are the ISO 14812 counterpart to the broader ont2md tooling used by RITSO topic ontologies. They are specialized for vocabulary groups/patterns, clause numbers, and SKOS-oriented term pages.

Prerequisites¶

Run the script from the repository root (the directory that contains mkdocs.yml and docs/).

Requirement	Purpose
`mkdocs.yml`	Site configuration; `nav` under Vocabulary is rewritten each run
`docs/`	Source `.ttl` files and generated Markdown / diagrams
`docs/itsVocabulary.ttl`	Master ontology (required)
Python 3	Runtime
RDFLib	Parse and query Turtle
Graphviz (`dot` on `PATH`)	Render class diagrams
PyYAML	Read/write `mkdocs.yml`

Minimum Python dependencies:

pip install rdflib pyyaml

Graphviz must be installed as a system package so the dot executable is available. For local site preview, also install Material for MkDocs and any plugins listed in mkdocs.yml.

Usage¶

cd /path/to/iso14812
PYTHONPATH=docs/python python docs/python/ttl2mkdocs.py

With a project virtual environment:

PYTHONPATH=docs/python .venv/bin/python docs/python/ttl2mkdocs.py

No command-line flags are accepted. Extra arguments print usage and exit with code 1.

Exit behavior¶

Situation	Result
Missing `mkdocs.yml` or `docs/`	Error message, exit `1`
Missing `docs/itsVocabulary.ttl` or failed vocabulary load	Error, exit `1`
Per-class / diagram / write errors	Logged into an errors list; processing continues where possible
Warnings only (for example clause gaps)	Printed during the run and again in the RUN SUMMARY; exit `0`
One or more errors	RUN SUMMARY lists them; exit `1`

At the end of every run, warnings and errors are reprinted in a RUN SUMMARY block on stderr so they are easy to find after long generation logs.

Turtle files in `docs/`¶

All Turtle modules reachable from itsVocabulary.ttl via owl:imports are loaded into one unified RDF graph. Classification is by basename:

Pattern	Example	Role
`itsVocabulary.ttl`	—	Master — home metadata, versioning, imports groups
`core.ttl`	—	Core — shared properties; not a nav group/pattern
`terms-group.ttl`	—	Terms hub — anchors Vocabulary navigation
`*-group.ttl`	`vehicleTerms-group.ttl`	Group — overview page listing patterns
`*-pattern.ttl`	`travellerTerms-pattern.ttl`	Pattern — overview page + member term pages

Editorial conventions for file and concept names are in ../guides/naming-conventions.md. Annotation expectations are in ../guides/ontology-formats.md.

Namespace and local concepts¶

The vocabulary namespace is fixed as https://w3id.org/itsdata/vocab/ (BASE in the Turtle files).

Only classes in that namespace that are treated as publishable terms receive individual Markdown pages. Display names come from skos:prefLabel (via get_label in utils.py). Page filenames use the preferred label (for example docs/terms/road vehicle.md).

Recommended annotations the scripts rely on¶

On module ontologies

Property	Used for
`dcterms:title`	Group/pattern titles and nav labels
`dcterms:description`	Master home text (and optional module blurbs)
`dcterms:modified`	Provenance on modules

On term classes

Property	Used for
`skos:prefLabel`	Page title and links
`skos:definition`	Lead definition
`:clause`	Clause line, sorting, pattern/group parent clause
`:altPrefLabel`, `skos:altLabel`, `skos:hiddenLabel`	Alternate / admitted / deprecated terms
`skos:note`, `skos:example`, `skos:historyNote`	Notes, examples, history
`dcterms:source`	Source line
`rdfs:subClassOf`, `owl:disjointWith`, property restrictions	Diagrams and “Relationships” tables

Clause validation¶

After patterns are collected, the processor warns when:

members of a pattern or group do not share the same root clause;
clause numbers overlap; or
clause numbers under a shared root are not contiguous.

These warnings appear inline and again in the run summary.

Page feedback links¶

Generated pages include a Comment on this page footer that opens a GitHub issue using .github/ISSUE_TEMPLATE/page-feedback.yml, prefilling page title and path. The repository URL is taken from mkdocs.yml repo_url.

owl:imports¶

Imports are followed from the master file using relative Turtle references (for example <vehicleTerms-group.ttl>). HTTP imports are skipped during discovery so generation does not depend on network access for this vocabulary’s own modules.

What the script generates¶

From the repository root, under docs/:

Output	Description
`index.md`	Site home from master ontology metadata (overwrites this file)
`terms/<prefLabel>.md`	One page per publishable term
`terms/groups/<Group Title>.md`	Group overview (patterns listed by parent clause)
`terms/patterns/<Pattern Title>.md`	Pattern overview (terms listed by clause)
`terms/concept_registry.md`	Alphabetical registry table
`diagrams/<term>.dot` / `.svg` / `.png`	Concept diagrams
`mkdocs.yml` `nav`	Leading ISO / TC 204 links preserved; generated tree nested under Vocabulary

Navigation structure written to `mkdocs.yml`¶

nav:
- TC204 on ISO.org: https://www.iso.org/committee/54706.html
- TC 204 Home: https://isotc204.org/
- Guides:
  - Overview: guides/index.md
  - Naming Conventions: guides/naming-conventions.md
  - Ontology Formats: guides/ontology-formats.md
  - Turtle: guides/turtle.md
  - Website Generation: python/README.md
- Vocabulary:
  - Home: index.md
  - Alphabetical Listing: terms/concept_registry.md
  - <Group>:
    - terms/groups/<Group>.md
    - <Pattern>:
      - terms/patterns/<Pattern>.md
      - <term>: terms/<term>.md

Any top-level nav entries before Vocabulary other than Guides are preserved when present; otherwise the two ISO/TC 204 links above are used as defaults. The Guides section is always rewritten to the canonical contributor-doc list.

Typical workflow¶

Edit or add Turtle under docs/ (prefer copying an existing *-pattern.ttl as a template).
Ensure the new pattern is imported by its group, and the group by itsVocabulary.ttl if needed.
From the repository root, run:

PYTHONPATH=docs/python python docs/python/ttl2mkdocs.py

Review the RUN SUMMARY for clause or processing issues.
Inspect generated Markdown under docs/terms/ and diagrams under docs/diagrams/.
Preview with mkdocs serve (or build/deploy via your usual MkDocs / CI process).

Sample module layout¶

docs/
├── itsVocabulary.ttl              # master
├── core.ttl                       # shared properties
├── terms-group.ttl                # nav hub
├── vehicleTerms-group.ttl         # group
│     imports vehicleComponentTerms-pattern.ttl, ...
├── vehicleComponentTerms-pattern.ttl
├── travellerTerms-pattern.ttl
└── python/
      └── ttl2mkdocs.py            # this toolchain