search

RDFLib / pyLODE

An OWL ontology documentation tool using Python and templating, based on LODE
BSD 3-Clause "New" or "Revised" License
167 stars 70 forks source link

Custom href for the RDF file link #131

Open smarie opened 3 years ago

smarie commented 3 years ago

Hi there, thanks once again for this great lib !

It seems that the current href link generated for the RDF (<dd><a href="...">RDF (turtle)</a></dd>) points to the local file used to generate the doc. Currently I modify the HTML by hand, but it would be great to be able to provide an alternative href directly.

If you think this is useful, I can try to propose a PR (but we should first probably agree on the option name/style then).

nicholascar commented 3 years ago

Hi @smarie, perhaps we can settle on an RDF property which, if present, will override the auto-generation of that link? I'd like to keep as much config as possible within the RDF file as this ensures that all the information in any HTML documentation is in the RDF too and not added through some hidden process.

Perhaps we can use dcterms:hasFormat since we are already using other DCTERMS annotations for the ontology. That property seems to be for this sort of thing - indicating other formats. We can't use dcterms:source as that's used to indicate non-RDF sources for the ontology/vocabulary itself in many ontologies documented with pyLODE.

If present then, that dcterms:hasFormat property could be expected to be a URI literal indicating a resolvable URI to an RDF version of the ontology. Perhaps like this:

<some-ontology>
    ...
    dcterms:hasFormat "http://somewhere-online.com/my/ont.ttl"^^xds:anyURI ;
    ...
.

Then we can just trigger a replacement of the original "source info" used to make an RDF file link (see common.py:117).

If this sounds sensible or if you can think of a better way, please do put in a PR!

smarie commented 3 years ago

Thanks for the quick feedback @nicholascar ! I'll discuss this and possible alternatives with colleagues and come back to you.

smarie commented 3 years ago

By the way, would this allow for relative links ? Indeed the problem is really related to deployment on a web server. So if we wish the documentation to be testable both on a local web server and the final remote one, a relative one is mandatory.

nicholascar commented 3 years ago

I think that if we allow an override property like this, then it's up to the deployer to cater for all the possibilities of their environment. Ideally, the URI would be an absolute one so that anyone having the ontology RDF would have a property that works, wherever they put the file, but if a relative URI is used, it would then just be considered a documentation property and that would be ok.

So yes, relative links could work.

I always perform 1, 2 or 3 HTML tidy-up tasks to ontologies produced by pyLODE to put in images and particular links when I deploy them. I have a couple that are auto-tidied through deployment scripting but mostly I only redeploy ontologies every now-and-then so it's not a big just to update a few bits. Not compared to the actual ontology updates themselves usually!

smarie commented 3 years ago

A few thoughts:

Semantically, dcterms:hasFormat seems to mean an alternative source. Here the need is rather "this file" (the source from the html doc generation, so the original rdf file). So I think that this information does not really fit in the file. You would not include in the file a path to itself, would you ? It seems overkill

I always perform 1, 2 or 3 HTML tidy-up tasks to ontologies produced by pyLODE

yes, this is exactly what I am referring to. For example I currently replace the image with a WebVowl iframe. All of these tasks, in my opinion, should not be configured by tags in the rdf. Rather, supporting a configuration file such as a custom section in setup.cfg (just like pytest, coverage, flake8, etc.) and/or a .pylode.cfg file to declare these standard operations in a very compact and user friendly way would make more sense. The href one is just one of them

nicholascar commented 3 years ago

Semantically, dcterms:hasFormat seems to mean...

Well easy for me to not implement it!

...supporting a configuration file such as a custom section in setup.cfg...

This might be the way to go! Just like we have several executable scripts and so on for different use, having a .pylode.cfg file or perhaps even several different one, does seem sensible.

If it's not about the ontology content but just deployment etc., then I'm fine with not using the RDF!

Perhaps you could test a first version cfg file to do all the parameterization that you want and then I'll see if I can adapt that for my needs. Then we can document the different configs.

smarie commented 3 years ago

Perhaps you could test a first version cfg file to do all the parameterization that you want and then I'll see if I can adapt that for my needs. Then we can document the different configs.

Makes sense. Starting small (just the configuration logic and a few options) and adding options later seems a good way to go. I'll try to propose something in the upcoming weeks. Thanks again @nicholascar !

nicholascar commented 3 years ago

No worries. I'm always happy to help people extend or implement pyLODE as sometimes I learn things from them!