pyLODE 2.x. An OWL ontology documentation tool using Python, based on LODE.
100K+
.. image:: https://badge.fury.io/py/pyLODE.svg :target: https://badge.fury.io/py/pyLODE
pyLODE
An OWL ontology documentation tool using Python and templating, based on LODE.
In addition to making human-readable forms of ontologies/taxonomies, pyLODE encourages ontology annotation best
practice by only producing good results for well documented inputs! pyLODe defines what it considers w'well documented'
in sections below, such as Profiles_ & What pyLODE understands_.
Quick Intro_What pyLODE understands_Profiles_Differences from LODE_Releases_The Live OWL Documentation Environment tool
(LODE <https://github.com/essepuntato/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 <https://www.essepuntato.it/lode>) is not always
online.
This tool is a complete re-implementation of LODE's functionality using
Python and Python's RDF manipulation module,
rdflib <https://pypi.org/project/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 <https://pypi.org/project/Jinja2/>.
The tool can be run as in these ways:
Falcon framework <https://falconframework.org/>__.pyLODE has been tested with all of the 30+ ontologies in pylode/examples/ <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, in HTML & Markdown. There are some examples of ADOC too.
For example, Epimorphic's <https://www.epimorphics.com/>__'s Registry Ontology is:
online version <https://epimorphics.com/public/vocabulary/Registry.html>_Another, the Australian Government's Records Interoperability Framework (AGRIF) Ontology:
rendered online by GitHack <https://raw.githack.com/RDFLib/pyLODE/master/pylode/examples/agrif.html>__the point-of-truth rendered online <https://linked.data.gov.au/def/agrif>__rendered online by GitHub <https://github.com/RDFLib/pyLODE/blob/master/pylode/examples/agrif.md>__resulting ADOC source <https://github.com/RDFLib/pyLODE/blob/master/pylode/examples/agrif.adoc>__rendered in HTML <https://github.com/RDFLib/pyLODE/blob/master/pylode/examples/agrif.adoc.html>__rendered online by GitHack <https://raw.githack.com/RDFLib/pyLODE/master/pylode/examples/agrif.vocpub.html>__You can build all of the example outputs locally by running pylode/examples/_make_examples.py <pylode/examples/_make_examples.py>_
which also serves as a good demonstration of calling pyLODE from a Python file.
Australia's Department of Finance's <https://www.finance.gov.au>__'s AGRIF ontology - http://linked.data.gov.au/def/agrif
Markdown version <https://github.com/AGLDWG/agrif-ont/blob/master/agrif.md>__National Archives of Australia <http://www.naa.gov.au>__'s Commonwealth Records Series ontology - http://linked.data.gov.au/def/crs
Markdown version <https://github.com/RDFLib/pyLODE/blob/master/pylode/examples/crs.md>__CSIRO's <https://www.csiro.au>__'s LocI ontology - http://linked.data.gov.au/def/lociGeological Survey of Queensland <https://www.business.qld.gov.au/industries/mining-energy-water/resources/geoscience-information/gsq>__'s
Boreholes Profile - http://linked.data.gov.au/def/boreholeGeoscience Australia <http://www.ga.gov.au/>__'s Place Names
Profile - http://linked.data.gov.au/def/placenamesEpimorphic <https://www.epimorphics.com/>__'s Registry Ontology
Semantic Web for Earth and Environmental Terminology <http://sweetontology.net>__ (SWEET)
See pairs of RDF & HTML files in the
pylode/examples/ <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 a hosted, online, service or even as a local web server that you can run. This repo contains executable files for Mac & Windows (soon Linux!) that you can use without any installation too.
The most important dependency to get correct when using this as a Python script of a command line program is the package rdflib which must be v5.0.0 or greater (see requirements.txt).
Do this to use pyLODE as a Python command line program.
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
To use pyLODE within Python, try something like this:
::
import pylode
html = pylode.MakeDocco(
input_data_file=input_file_path,
outputformat="html",
profile="ontdoc"
).document()
You will now have the HTML content within the variable html.
For desktop command line use, just clone this repository and either use cli.py as per the command line instructions below or use makedocco.py as a Python script directly.
pyLODE presents natively as a Python command-line utility,
pylode/cli.py <pylode/cli.py>__ and there are also a BASH, Windows & Mac OS options available for command line use:
pylode/bin/pylode.sh <pylode/bin/pylode.sh>__ - BASH scriptpylode/bin/pylode.app <pylode/bin/pylode.app>__ - MAC OS command line executable scriptpylode/bin/pylode.exe <pylode/bin/pylode.exe>__ - Windows command line executableAll use the same command line arguments.
Additionally, there is a Falcon framework <https://falconframework.org/>__ local HTTP server option.
Also, a web UI for pyLODE is available at <https://pylode.surroundaustralia.com>.
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
-u or --url, required if -i not used
-c or --css, optional, default 'true'
-o or --outputfile, optional
-f or --outputformat, optional, default 'html'
-p or --profile, optional, default 'ontdoc'
Simple Knowledge Organization System (SKOS) <https://www.w3.org/TR/skos-reference/>) vocabularies or SKOS versions of OWL ontologies, "prof" for Profiles Vocabularies <https://www.w3.org/TR/dx-prof/> profiles. See -lp for all profiles supported.-lp or --listprofiles, optional, no arguments
This basic call to the BASH script in pylode/bin/ <pylode/bin/>__ will
print to standard out an HTML document for an ontology called placenames.html.
::
./pylode -i ../example/prof.ttl
An output file could be specified by using -o, rather than printing to standard out.
An online version of pyLODE is now available at https://pylode.surroundaustralia.com/.
Install locally by first building the container
::
docker build -t pylode:latest --build-arg PYTHON_VERSION=3.8-slim .
Then run the container
::
docker run -it -d -p 8000:8000 -e GTAGID=${Google TagID} pylode
N.B. The Google TagID is NOT required unless Google Analytics is required.
It looks as follows GTAGID=UA-168806395-1.
You can now access the service on localhost
::
curl localhost:8000/lode?url=http://sweetontology.net/sweetAll.ttl
You can run pyLODE using your own, local, HTTP server like this:
::
gunicorn --chdir /path/to/pyLODE/pylode server:api
The server is then available at localhost:8000 and localhost:8000/pylode for the active endpoint. Note that the server must be fed a URL to an ontology to document supplied by a server 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.
::
curl localhost:8000/pylode?url=http://sweetontology.net/sweetAll.ttl
In pylode/bin/, a Windows executable, pylode.exe is available for command line use.
Be sure to add pylode.exe to your Windows user's PATH variable so you can run pylode.exe from any folder. Just run the Registry Editor (search for "Regedit" in the Start menu) and then navicate to HKEY_CURRENT_USER > Environment > Path. Adding the full path of the folder pylode/bin/ to Path will ensure you can run pylode.exe within the Windows command prompt, regardless of what folder you are in.
You can rebuild the pylode.exe file from the source code, if you like. Use the Python program Pyinstaller <https://www.pyinstaller.org/>__ as per
its instructions <https://pyinstaller.readthedocs.io/en/stable/usage.html>__. The created pylode.exe will have the same characteristics as the Linux/Mac
CLI program.
Pyinstaller uses a .spec file to make the binary and that is included in this repository: pylode-cli.spec.
See the PyInstaller installation guide <https://pyinstaller.readthedocs.io/en/stable/installation.html#installing-in-windows>__
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 pylode
pyinstaller pylode-cli.spec
This will output pylode.exe in the dist directory in pylode. The .exe file in bin/ is just the latest copy of this.
You can now run the pyLODE Command Line utility via pylode.exe.
See above for the pyLODE command line util usage instructions.
In pylode/bin/, there is a Mac executable, pylode.app.
As per instructions for PyInstaller use on Windows, you can rebuild the file pylode.app using pylode.spec, if you wish.
In pylode/bin/, there is a shell script pylode.sh. You can run this on the command line. It just pushes queries to the Python command line cli.py.
pyLODE understands Ontologies, Taxonomies & Profiles and handles them based on the Ontology Document, Vocabulary Publication and PROF profiles that it contains. These three profiles share understanding of basic annotation properties.
pyLODE understands the following ontology constructs:
owl:importsrdfs:label, skos:prefLabel, dct:title or dc:titlerdfs:comment, skos:definition, dct:description or dc:description
skos:historyNote
owl:versionIRI as a URIowl:versionInfo as a string
vann:preferredNamespacePrefix as a tokenvann:preferredNamespaceUri as a URIpylode/examples/ <pylode/examples/>__ directory for examples!dct:created etc., all as xsd:date or xsd:dateTime datatype propertiesdct:license as a URI & rights - dct:rights as a stringschema:codeRepository as a literal of type xsd:anyURIdcterms:source as a literal of type xsd:anyURI or textrdfs:Class or owl:Classrdfs:label or skos:prefLabel or dct:titlerdf:comment, skos:definition, dct:description as a string or using inline HTML or Markdown <https://daringfireball.net/projects/markdown/>__skos:scopeNote as a literal
skos:example
owl:subClassOf somethingowl:subClassOf of an owl:Restriction with any of the normal cardinality or property existence etc. restrictionsowl:ObjectProperty, owl:DatatypeProperty or owl:AnnotationPropertyrdfs:label or skos:prefLabel or dct:title string literalrdf:comment, skos:definition, dct:description string literal
skos:scopeNote string literal
skos:example
owl:subPropertyOf somethingowl:equivalentProperty somethingowl:inverseOf somethingrdfs:domain or schema:domainIncludesrdfs:range or schema:rangeIncludeshttp://prefix.cc <http://prefix.cc/>__owl:sameAsExample Handling
pyLODE can handle many forms of examples for Classes & Properties and can handle multiple examples per class/property. In all cases, the example value is indicated with a ``skos:example`` property like this:
::
<x>
a owl:Class ;
skos:example {Literal, Blank Node or URI}
.
**Simple Literals**
The most basic form is an example that is a literal with no format type indicated. This will be printed out in monospaced text, e.g. the Class ``Fish`` in the `Examples Ontology <https://raw.githack.com/RDFLib/pyLODE/master/pylode/examples/examples-ont/examples.html>`_ has a plain Turtle example like this:
::
<x> a eggs:Fish ;
skos:prefLabel "Fish X"@en ;
eggs:livesInFreshWater true ;
...
.
If you indicate one of the RDF built-in formats (``rdf:HTML``, ``rdf:XMLLiteral`` or ``rdf:JSON``), it will be interpreted in the markup form specified, which means, in practice, that HTML will be rendered where as XML or JSON will be monospaced. The Examples Ontology has this HTML example for the property ``has scale colour``:
----
**scale colour:**
* blue
* orange
* white
----
You can use Markdown in example literals too, but to do so, you must set the format to ``text/markdown`` so see the *Resource Descriptor* method below.
**URIs**
If you put a URI in the example field like this: ``<x> skos:example <...> ;`` or like this ``<x> skos:example "..."^^xsd:anyURI ;`` then pyLODE will render it as a clickable hyperlink in HTML, Markdown or ASCIIDOC, as per your chose output format.
**Images**
You can use images in the example field. To do so, either use a URI to an image on the web or a relative URI to a local image file. pyLODE will render either form as an inline image. See the `Fish Food class example <https://raw.githack.com/RDFLib/pyLODE/master/pylode/examples/examples-ont/examples.html#FishFood>`_ that looks like this:
.. image:: examples/examples-ont/fish-food.png
**"Resource Descriptor" Examples**
To do more you can use a `Profiles Vocabulary (PROF) <https://w3c.github.io/dx-prof/prof/>`__ ``ResourceDescriptor`` to define multiple properties for an example resource. This involves defining a ``ResourceDescriptor`` either as a Blank Node or a URI node like this, the `Examples Ont 'eats' property <https://raw.githack.com/RDFLib/pyLODE/master/pylode/examples/examples-ont/examples.html#FishFood>`_:
::
:eats skos:example :eats-example .
:eats-example
a prof:ResourceDescriptor ;
dcterms:format "text/turtle" ;
dcterms:conformsTo <https://example.com> ;
prof:hasArtifact """<x> a :Creature ;
:eats <y> ;
.
<y> a :Food .""" ;
.
Here the ``ResourceDescriptor`` says that this example is in the ``text/turtle`` format, has an inline artifact (the actual example text) and conforms to something, in this case the profile defined by ``<https://example.com>``.
You can use this ``ResourceDescriptor`` method to create multiple examples for a class or property that conform to different things (perhaps profiles of your ontology).
Agents
------
Agents, individual persons or organisations, should be associated with ontologies/taxonomies/profiles to indicate *authors*, *creators*, *publishers* etc. There are 2 ways to do this that pyLODE understands: datatype & object type.
Datatype - not preferred
A simple literal value for an agent that a human can read but not a machine can't understand:
<ONTOLOGY_URI> dc:creator "AGENT NAME" .
^^xsd:string) or language typed (@en or @de)Dublin Core Elements 1.1 <https://www.dublincore.org/specifications/dublin-core/dcmi-terms/#section-3>__ properties may be used:
dc:contributordc:creatordc:publisherschema.org <https://schema.org>__ properties may be used:
schema:authorschema:contributorschema:creatorschema:editorschema:funderschema:publisherschema:translator::
<ontology_x>
dc:creator "Nicholas J. Car" ;
Object type - preferred
An RDF object is used for the agent and can contain multiple details. A Blank Node or a URI can be used. Best case, a persistent agent URI!
.. figure:: img/contributor-object.png
:align: center
:figclass: figure-eg
.....
* ``<ONTOLOGY_URI> dct:creator [...] .``
or
* ``<ONTOLOGY_URI> dct:creator <SOME_URI> .``
* the range value is a Blank Node or a URI of type:
* ``schema:Person``
* ``schema:Organization``
* ``foaf:Person``
* ``foaf:Organization``
* the properties of the Blank Node or the URI are as below
* the following `Dublin Core Terms <https://www.dublincore.org/specifications/dublin-core/dcmi-terms/#section-2>`__ properties may be used:
* ``dct:contributor``
* ``dct:creator``
* ``dct:publisher``
* ``dct:rightsHolder``
* the following `schema.org <https://schema.org>`__ properties may be used:
* ``schema:author``
* ``schema:contributor``
* ``schema:creator``
* ``schema:editor``
* ``schema:funder``
* ``schema:publisher``
* ``schema:translator``
* the following `FOAF <http://xmlns.com/foaf/spec/>`__ properties may be used:
* ``foaf:maker``
e.g. (Blank Node):
::
<ontology_x>
schema:editor [
a schema:Organization ;
...
] ;
or (URI):
::
<ontology_x>
schema:editor <https://orcid.org/0000-0002-8742-7730> ;
...
<https://orcid.org/0000-0002-8742-7730>
a foaf:Person ;
...
Agent datatype properties
^^^^^^^^^^^^^^^^^^^^^^^^^
* ``foaf:name`` / ``schema:name``
* ``foaf:mbox`` / ``schema:email``
* ``foaf:homepage`` / ``schema:url``
* ``schema:identifier``
e.g.:
::
<ontology_x>
dct:creator [
schema:name "Nicholas J. Car" ;
schema:identifier <http://orcid.org/0000-0002-8742-7730> ;
schema:email <mailto:[email protected]> ;
] ;
Linking a Person to an Organization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Use ``schema:member``, ``schema:affiliation`` (there is no FOAF Person -> Group/Org property):
e.g.:
::
<ontology_x>
dct:creator [
schema:name "Nicholas J. Car" ;
schema:identifier <http://orcid.org/0000-0002-8742-7730> ;
schema:email <mailto:[email protected]> ;
schema:affiliation [
schema:name "SURROUND Australia Pty Ltd" ;
schema:url <https://surroundaustralia.com> ;
] ;
] ;
Provenance
----------
Ontology/Taxonomy Source
The ontology's HTML representation linking back to the RDF: generated automatically
.. figure:: img/source.png :align: center :figclass: figure-eg
.....
Code Repositories
Indicating to readers where the 'live' version of the ontology/taxonomy is managed:
.. figure:: img/code-repository.png
:align: center
:figclass: figure-eg
.....
This should not be done for profiles, instread, create a ``prof:ResourceDescriptor`` instance with ``role:repository`` to indicate a profile's repository.
Code repositories that house an ontology can be indicated either using `schema.org's codeRepository property <https://schema.org/codeRepository>`__ or a combination of the `Description of a Project <https://github.com/ewilderj/doap>`__ and PROV:
::
@prefix schema: <https://schema.org/> .
<ONTOLOGY_URI>
schema:codeRepository <REPO_URI> ;
...
or
::
@prefix doap: <http://usefulinc.com/ns/doap#> .
@prefix prov: <http://www.w3.org/ns/prov#> .
<ONTOLOGY_URI>
prov:wasGeneratedBy [
a doap:Project , prov:Activity ;
doap:repository <REPO_URI>
]
...
e.g., for the `ontology version on ISO 19160-1 <http://linked.data.gov.au/def/iso19160-1-address>`__:
::
<http://linked.data.gov.au/def/iso19160-1-address>
prov:wasGeneratedBy [
a doap:Project , prov:Activity ;
doap:repository <https://github.com/AGLDWG/iso19160-1-address-ont>
] ;
...
Styling
-------
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 styli
Content type
Image
Digest
sha256:221e51477…
Size
211.8 MB
Last updated
about 2 years ago
docker pull secoresearch/pylodePulls:
862
Last week