An OWL ontology documentation tool using Python and templating, based on LODE.
- Quick Intro
- Examples
- Installation
- Use
- What pyLODE understands
- Differences from LODE
- License
- Citation
- Collaboration
- Contacts
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 (old-style HTML, use of older technologies like XSLT) and it's (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 or Markdown is generated using basic Python scripting and Python's Jinja2 templating.
The tool can be run as in these ways:
- Python command line
- cli.py in the main folder
- BASH command line
- bin/ directory, uses cli.py
- as-a-service locally
- via the popular Falcon framework.
- see server.py in the main folder
- as-a-service online
- hosted at https://kurrawong.net/pylode-online
pyLODE has been tested with all of the 30+ ontologies in src/pylode/examples/ and we are trying to ensure it captures all of their annotations. For each example, there is the original RDF file and the corresponding output, either HTML, Markdown or both.
For example, Epimorphic's's Registry Ontology is:
- reg.ttl - source file
- reg.html - HTML output
- reg.md - Markdown output
- see this rendered online by GitHub
- Australia's Department of Finance's's AGRIF ontology - http://linked.data.gov.au/def/agrif
- see the Markdown version
- National Archives of Australia's Commonwealth Records Series ontology - http://linked.data.gov.au/def/crs
- see the Markdown version
- CSIRO's's LocI ontology - http://linked.data.gov.au/def/loci
- Geological Survey of Queensland's Boreholes Profile - http://linked.data.gov.au/def/borehole
- Geoscience Australia's Place Names Profile - http://linked.data.gov.au/def/placenames
- Epimorphic's Registry Ontology - https://epimorphics.com/public/vocabulary/Registry.html
- Semantic Web for Earth and Environmental Terminology (SWEET)
See pairs of RDF & HTML files in the pylode/examples/ directory for other, preprocessed examples.
This tool can be used either as a command line utility (Linux, Mac or Windows, see below) or as a Python module in other Python code. It can also be used via an online API.
This tool is available on PyPI, the Python Package Index, at https://pypi.org/project/pyLODE/ and can be installed for use as a Python module via pip:
pip install pylode
For desktop command line use, just clone this repository and either use Python or the provided BASH scrip (see below).
pyLODE presents as a Python & BASH command-line utility, pylode/cli.py & pylode/bin/pylode respectively as well as a server implementation powered by the Falcon framework. Windows scripts may appear soon. All use the same command line arguments.
An online API to access pyLODE is now available in test mode at https://kurrawong.net/pylode-online.
You can run pyLODE using your own, local, HTTP server like this:
`
gunicorn server:api
`
Then, in another terminal:
`
curl localhost:8000/lode?url=http://sweetontology.net/sweetAll.ttl
`
These are the command line arguments to run pyLODE as a BASH or Python script on Linux, Mac etc. or via the Windows executable:
-i
or--inputfile
, required if-u
not used- The RDF ontology file you wish to generate HTML for Must be in either Turtle, RDF/XML, JSON-LD or N-Triples formats indicated by the file type extensions .rdf, .owl, .ttl, .n3, .nt, .json respectively
-u
or--url
, required if-i
not used- The RDF ontology you wish to generate HTML for, online. Must be an absolute URL that can be resolved to RDF, preferably via Content Negotiation.
-c
or--css
, optional, default 'false'- Whether (true) or not (false) to copy the default CSS file to the output directory.
-o
or--outputfile
, optional- A name you wish to assign to the output file. Will be postfixed with .html or .md. If not specified, the name of the input file or last segment of RDF URI will be used, + .html/.md.
-f
or--outputformat
, optional, default 'html'- The output format of the documentation. 'html' or 'md' accepted.
This call to the BASH script in pylode/bin/ will
create an HTML document for an ontology called placenames.html
and
save it with a basic CSS file into
pylode/output_files/:
$ ./pylode -i ../example/prof.ttl --css true
Pyinstaller can be
used to create an
executable for Windows that has the same characteristics as the Linux/Mac
CLI program.
The necessary .spec
file is already included in pylode-cli.spec
.
The pylode-cli.spec
PyInstaller spec file creates a .exe
for the
pyLODE Command Line utility. See above for the pyLODE command line util usage instructions.
See the PyInstaller installation guide for info on how to install PyInstaller for Windows.
Once you have pyinstaller, use pyinstaller to generate the pyLODE.exe
CLI file like so:
$ cd src/pylode $ pyinstaller pylode-cli.spec
This will output pylode.exe
in the dist
directory in src/pylode
.
You can now run the pyLODE Command Line utility via pylode.exe
.
See above for the pyLODE command line util usage instructions.
pyLODE understands the following ontology annotations:
- ontology metadata
- imports -
owl:imports
- title -
rdfs:label
orskos:prefLabel
ordct:title
ordc:title
- description -
rdfs:comment
orskos:definition
ordct:description
ordc:description
- Markdown is supported
- description -
- historyNote -
skos:historyNote
- Markdown is supported
- historyNote -
- version URI -
owl:versionIRI
as a URI - version info -
owl:versionInfo
as a string - preferred namespace prefix -
vann:preferredNamespacePrefix
as a token - preferred namespace URI -
vann:preferredNamespaceUri
as a URI
- preferred namespace prefix -
- version info -
- agents: publishers, creators, contributors
- see Agent Formatting below for details
- see the pylode/examples/ directory for examples!
- dates: created, modified, issued -
dct:created
etc., all asxsd:date
orxsd:dateTime
datatype properties - rights: license -
dct:license
as a URI & rights -dct:rights
as a string
- imports -
- classes
- per
rdfs:Class
orowl:Class
- title -
rdfs:label
orskos:prefLabel
ordct:title
- description -
rdf:comment
orskos:definition
ordct:description
as a string or usingc`Markdown <https://daringfireball.net/projects/markdown/>`__ or HTML - usage note - a
skos:scopeNote
string - super classes - by declaring a class to be
owl:subClassOf
something - sub classes - pyLODE will work these out itself
- restrictions - by declaring a class to be
owl:subClassOf
of anowl:Restriction
with any of the normal cardinality or property existence etc. restrictions - in domain/range of - pyLODE will auto-calculate these
- per
- properties
- per
owl:ObjectProperty
,owl:DatatypeProperty
orowl:AnnotationProperty
- title -
rdfs:label
orskos:prefLabel
ordct:title
- description -
rdf:comment
orskos:definition
ordct:description
- usage note - a
skos:scopeNote
string - super properties - by declaring a class to be
owl:subPropertyOf
something - sub properties - pyLODE will work these out itself
- domains -
rdfs:domain
orschema:domainIncludes
- ranges -
rdfs:range
orschema:rangeIncludes
- per
- namespaces
- pyLODE will honour any namespace prefixes you set and look up others in http://prefix.cc
- it will either read your ontology's default/base URI in annotations or guess it using a number of methods
- named individuals
- coming!
- Use either the DC versions of properties (
dc:publisher
etc.) or the DCT versions (dct:publisher
etc.) - if using the DC form, the range should just be a string, e.g.
dc:publisher "Geoscience Australia" .
ordc:creator "Nicholas J. Car" .
- if using the DCT form, the range should be a
foaf:Agent
orschema:Person
Blank Node or URI (if details are given elsewhere in the ontology) with the following properties: foaf:name
/sdo:name
foaf:mbox
/sdo:email
foaf:homepage
/schema:identifier
/sdo:url
- if using the DCT form, the range should be a
- Affiliation of people to organisation can be made if schem.aorg is used using
sdo:member
orsdo:affiliation
(latter preferred) - e.g.
- Affiliation of people to organisation can be made if schem.aorg is used using
<ontology_x> dct:creator [ sdo:name "Nicholas J. Car" ; sdo:identifier <http://orcid.org/0000-0002-8742-7730> ; schema:email <mailto:nicholas.car@surroundaustralia.com> ; sdo:affiliation [ sdo:name "SURROUND Australia Pty Ltd" ; sdo:url <https://surroundaustralia.com> ; ] ; ] ;
To help pyLODE understand more annotations, see Suggestions below.
When an HTML document is generated, i.e. not Markdown or other format,
schema.org metadata is added to the HTML
header in the form of properties of a DigitalDocument
subject.
The schema.org properties catered for are:
name
dateCreated
dateModified
description
license
copyrightYear
repository
Not yet handled, but will be soon, are:
publisher
creator
copyrightHolder
Please suggest any more required schema.org annotations!
This tool generates HTML that is shamelessly similar to LODE's styling. That's because we want things to look familiar and LODE's outputs look great. The Markdown's pretty vanilla.
Also, pyLODE generates and uses only static HTML + CSS, no JavaScript, live loading Google Fonts etc. This is to ensure that all you need for nice display is within a couple of static, easy to use and maintain, files. Prevents documentation breaking over time.
Feel free to extend your styling with your own CSS.
- 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 more modern & simpler HTML
- catering for a wider range of ontology options such as:
- schema.org
domainIncludes
&rangeIncludes
for properties
- schema.org
- better Agent linking
foaf:Agent
orschema:Person
objects for creators, contributors & publishers- you can still use simple string peoperties like
dc:contributor "Nicholas J. Car"
too if you really must!
<ontology_x> dct:creator [ sdo:name "Nicholas J. Car" ; sdo:identifier <http://orcid.org/0000-0002-8742-7730> ; ] ;
- 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
- active development
- this software is in use and will be improved for the foreseeable future so we will cater for more and more things
- recent ontology documentation initiatives such as the MOD Ontology will be handled, if requested
This code is licensed using the GPL v3 licence. See the LICENSE file for the deed. Note Citation below though for attribution.
If you use pyLODE, please leave the pyLODE logo with a hyperlink back here in the top left of published HTML pages.
The maintainers welcome any collaboration.
If you have suggestions, please email the contacts below or leave Issues in this repository's Issue tracker.
But the very best thing you could do is create a Pull Request for us to action!