pyLODE

An OWL ontology documentation tool using Python, based on LODE.

In addition to making web page, human-readable forms of ontologies, pyLODE encourages ontology annotation best practice by only producing good results for well documented inputs! pyLODE defines what it considers “well documented” in sections below, e.g. What pyLODE understands.

New mode: In v3.1.0, pyLODE now has a new mode called supermodel, in addition to the existing ontpub & vocpub modes. This new mode allows for documenting profiles and modules of multipart models. See supermodel.md for more information.

Contents

1. Quick Intro
2. Use
3. What pyLODE understands
4. Examples
5. Installation
6. Testing
7. Differences from LODE
8. Releases
9. License
10. Citation
11. Collaboration
12. Contacts

Quick Intro

The Live OWL Documentation Environment tool
(LODE) is a well-known (in Semantic Web circles) Java & XSLT-based tool used to generate human-readable HTML documents for OWL and RDF ontologies. That tool is now a bit dated and its online version is not always online.

This tool is a complete re-implementation of LODE’s functionality using Python and Python’s RDF manipulation module, rdflib. An ontology to be documented is parsed and inspected using rdflib and HTML is generated directly using Python’s dominate package.

Use

The tool can be used in multiple ways:

• BASH command line script
  • pyLODE.sh in bin/
• Windows EXE
  • pyLODE.exe in bin/
• Mac executable
  • pyLODE in bin/
• Python script
  • cli.py or module
• As-a-service locally
  • via the Falcon framework
  • see server.py
• As-a-service online
  • https://tools.kurrawong.ai/pylode

Command line arguments

usage: pylode [-h] [-v] [-o OUTPUTFILE] [-c {true,false}] [-s {true,false}] [-p {ontpub,valpub,vocpub,supermodel}] [-l {error,warning,info,debug}] input

positional arguments:
  input                 Input file location or URL

options:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit
  -o, --outputfile OUTPUTFILE
                        A name you wish to assign to the output file. Will be postfixed with .html if not already added. If no output file is given, output will be printed to screen
  -c, --css {true,false}
                        Whether (true) or not (false) to include CSS within an output HTML file.
  -s, --sort {true,false}
                        Whether (true) or not (false) to sort ontology subjects in the output.
  -p, --profile {ontpub,valpub,vocpub,supermodel}
                        Which profile to use to generate HTML. Must be one of 'ontpub' (https://linked.data.gov.au/def/ontpub) - for ontologies, 'valpub' (https://linked.data.gov.au/def/valpub) - for SHACL
                        Shapes Graphs, 'vocpub' (https://linked.data.gov.au/def/vocpub) - for SKOS vocabularies, 'supermodel' - for profiles of profiles. If omitted, the profile is inferred from the input RDF.
  -l, --loglevel {error,warning,info,debug}
                        Set the logging level

Basic Use

As a Python script

python pylode examples/ontpub/minimal.ttl -o minimal.html

for a SKOS vocabulary:

python pylode examples/vocpub/GeologicSpecimenMaterialTypes.ttl -o GeologicSpecimenMaterialTypes.html

for the same SKOS vocabulary with the vocpub being forciply selected:

python pylode examples/vocpub/GeologicSpecimenMaterialTypes.ttl -o GeologicSpecimenMaterialTypes.html -p vocpub

As a Docker container

docker build -t pylode:latest .

docker run --rm -v <ttl_directory>:/data pylode:latest <ttl_file> -o <html_file>

Note: <ttl_directory> must be absolute; <ttl_file> and <html_file> are relative to it

Via a stand-alone server

The pyLODE server uses the popular Falcon framework to implement a lightweight web api.

It can be run standalone as a single-thread, single process HTTP server, or more robustly as a WSGI application with GUnicorn.

In all launch methods listed here, the server will be available at http://localhost:8000 for the landing page and http://localhost:8000/pylode for the active endpoint.

The active endpoint accepts the following querystring parameters:

• url for the absolute URL of the ontology document that you wish to render. The server hosting that ontology document must be capable of responding to Content Negotiation, i.e. it must supply RDF according to an HTTP Accept request for text/turtle, application/rdf+xml etc.
• profile for the profile to use to generate HTML. Must be one of:
  • ontpub for ontologies. This is the default if no profile is provided.
  • vocpub for SKOS vocabularies
  • valpub for SHACL ShapesGraphs
  • supermodel for profiles of profiles
• sort to indicate whether subjects should be sorted in the rendered output. Must be one of:
  • true to sort the subjects (this is the default)
  • false to NOT sort the subjects

Here's an example of use with the AGRIF Ontology using the source in this repository:

http://localhost:8000/pylode?url=https://raw.githubusercontent.com/RDFLib/pyLODE/refs/heads/master/examples/ontpub/agrif.ttl

The LODE responses generated by the server can be globally customised by setting the following optional environment variables:

• CSS_URL can be set to the absolute URL of a CSS stylesheet hosted elsewhere that should be referenced by pyLODE documents
• FAVICON_URL can be set to the absolute URL of a favicon image hosted elsewhere that should be referenced by pyLODE documents
• FAVICON_MIME should be set to the MIME type of the resource at FAVICON_URL if that has been configured (e.g. image/png)
• GTAGID can be set to a Google Analytics Tag ID that you would like to use for tracking requests to your server.

Launch the pyLODE server standalone from your local directory:

You will need a few extra python modules installed locally:

pip install bs4 falcon validators

You can then run the pyLODE Server in standalone mode like this:

python -m pylode.server

Build and run the docker image for the pyLODE Standalone Server:

docker build --target=pylode-server -t pylode-server:latest .
docker run --rm -p 8000:8000 pylode-server:latest

Build and run the docker image for the pyLODE GUnicorn Server:

docker build --target=pylode-gunicorn -t pylode-gunicorn:latest .
docker run --rm -p 8000:8000 pylode-gunicorn:latest

Module Use

For OWL

from pylode.profiles.ontpub import OntPub

od = OntPub(ontology="some-ontology-file.ttl")
html = od.make_html()
od.make_html(destination="some-resulting-html-file.html")

For SKOS

from pylode.profiles.vocpub import VocPub

od = VocPub(ontology="some-ontology-file.ttl")
html = od.make_html()
od.make_html(destination="some-resulting-html-file.html")

Examples

The examples/ directory contains multiple RDF & HTML pairs.

Rendered examples:

• minimal.html
• agift.html
• alternates.html
• asgs.html

What pyLODE understands

pyLODE understands definitional ontologies (owl:Ontology), classes, properties & axioms, vocabularies (skos:ConceptScheme), concepts and collections and SHACL Shapes Graphs (sh:ShapesGraph or owl:Ontology when containing shapes), Node and Property Shapes.

pyLODE will try and render all ontology/vocab annotation elements, in an order starting with those listed per type of element in rdf_elements.py and then anything else it finds.

Notes on Agents

pyLODE supports simple and complex Agent objects, including ORCIDs, affiliations, and contact details.

PREFIX schema: <https://schema.org/>
PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>

<ontology_x>
    schema:creator [
        schema:name "Nicholas J. Car" ;
        schema:identifier <http://orcid.org/0000-0002-8742-7730> ;
        schema:email "nick@kurrawong.ai"^^xsd:anyURI ;
        schema:affiliation [
            schema:name "KurrawongAI" ;
            schema:url "https://kurrawong.ai"^^xsd:anyURI ;
        ] ;
    ] ;
.

Installation

pyLODE is available on PyPI:

pip install pylode

Testing

python -m pytest tests --disable-warnings

Differences from LODE

• command line access
  • you can use this on your own desktop so you don't need me to maintain a live service for use
• use of modern simple HTML
  • no JavaScript: pyLODE generates static HTML pages
• catering for a wider range of ontology options such as:
  • schema.org domainIncludes & rangeIncludes for properties
• better Agent representation
  • see the Notes on Agents section above
• smarter CURIES
  • pyLODE caches and looks up well-known prefixes to make more/better CURIES
  • it tries to be smart with CURIE presentation by CURIE-ising all URIs it finds, rather than printing them
• reference ontologies property labels
  • pyLODE caches ~ 10 well-known ontologies (RDFS, SKOS etc), properties from which people often use for their ontology documentation. Where these properties are used, the background ontology's labels are use
• active development
  • pyLODE has been under active development since mid-2019 and is still very much actively developed - it's not just staying still
  • it will be improved in foreseeable to cater for more and more things
  • recent ontology documentation initiatives such as the MOD Ontology will be handled, if requested

Releases

Since version 3.0.1, we have moved to documenting releases in GitHub: https://github.com/RDFLib/pyLODE/releases

Older releases

License

This code is licensed using the BSD 3-Clause licence. See the LICENSE file for the deed. Note Citation below though for attribution.

Citation

If you use pyLODE, please leave the pyLODE logo with a hyperlink back here in the top left of published HTML pages.

Collaboration

Contributions are welcome!

Please submit issues or pull requests via the issue tracker.

But the very best thing you could do is create a Pull Request for us to action!

Contacts

Author:
Nicholas Car
Data Architect
KurrawongAI
nick@kurrawong.ai

Release Procedure

1. tidy code: $ task format
2. pass all tests: $ task test
3. increment version number in pyproject.toml
4. commit all changes $ git commit -a "..."
5. tag with version number: $ git tag ...
6. push changes $ git push
7. push version git push --tags
8. make a GitHub release
   • PyPI release is automated from this in pypi.yml
9. increment version number to next release alpha in pyproject.toml
10. commit all changes $ git commit -a "..."
11. push changes $ git push