Rewriting ontodoc based on domain-battery

[jesper-friis]

Description

Rewriting and simplifying the ontodoc tool based on domain-battery. For now the python module is called ontodoc_rst.py.

Structure the generated document as follows:

==========
References
==========

Module: <first_module_name>
===========================

-------
Classes
-------

<class1>
--------

...

For each module, document:

• classes
• object properties
• data properties
• annotation properties
• individuals
• datatypes

Tasks

• Reproduce all information included in the battery.rst file
• Add tooling for creating other needed files, like index.rst (just a template that the user can improve)
• Add a new ontodoc script/tool - instead of adding a new tool, the old ontodoc tool was extended to support .rst output. It doesn't run sphinx automatically, though...
• Add small tutorial of how to use the tool
• Add ontology metadata documentation to generated documentation
• Add more semantic information to generated documentation
• Add language to keys for localised values
• Add default css file (common for all EMMO domain ontologies, could e.g. be downloaded from a common source...)
• Add support for figures (e.g. by displaying links to known image formats as images)
• Sort modules in a logical order, e.g. by namespace and import depth
• Add a module dependency graph at the top
• Add subclasses to generated documentation to support navigating the taxonomy
• Is it possible to collapse the sidebar to make it easier to navigate to the right module?
• Add anchor by prefLabel, to make it easier for people to find the IRI when one knows the prefLabel

The last points can maybe be done in a separate PR.

Type of change

• Bug fix.
• New feature.
• Documentation update.
• Test update.

Checklist

This checklist can be used as a help for the reviewer.

• Is the code easy to read and understand?
• Are comments for humans to read, not computers to disregard?
• Does a new feature has an accompanying new test (in the CI or unit testing schemes)?
• Has the documentation been updated as necessary?
• Does this close the issue?
• Is the change limited to the issue?
• Are errors handled for all outcomes?
• Does the new feature provide new restrictions on dependencies, and if so is this documented?

Comments

[codecov]

Codecov Report

Attention: Patch coverage is 89.05473% with 22 lines in your changes are missing coverage. Please review.

Project coverage is 73.22%. Comparing base (60dda59) to head (bf1fc98).

Files	Patch %	Lines
ontopy/ontodoc_rst.py	88.16%	20 Missing ⚠️
ontopy/excelparser.py	0.00%	1 Missing ⚠️
ontopy/utils.py	95.83%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #742      +/-   ##
==========================================
+ Coverage   72.11%   73.22%   +1.11%     
==========================================
  Files          17       18       +1     
  Lines        3486     3683     +197     
==========================================
+ Hits         2514     2697     +183     
- Misses        972      986      +14     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[francescalb]

I am not so happy about tests that dowload EMMO. We already have many of those and they make the tests very slow.

[jesper-friis]

Replaced it with the local animal ontology.

[francescalb]

Does this test what is actually created?

[jesper-friis]

Added simple tests for generated content...

[francescalb]

Why?

[jesper-friis]

Because onto.save() stores other files in addition to isq.rdfxml and the catalogue file. Explicitly checking for all created files will fail when new modules are added to EMMO disciplines.

[francescalb]

Why this? It is more difficult to read.

[jesper-friis]

I agree that it is more difficult to read. But without this, the test is failing since onto.save() creates other files in addition to isq.rdfxml and the catalogue file.

We can either explicitly checking for all created files, but that will fail when new modules are added to EMMO disciplines.

Would it be more readable to rewrite the test as

created_files = set(os.listdir(outputdir2 / "emmo.info" / "emmo" / "disciplines"))
for fname in ("chameo.rdfxml", "catalog-v001.xml"):
    assert fname in created_files

[francescalb]

yes, I prefer this.

[jesper-friis]

done

[francescalb]

Approved, but I prefer the change in one of the tests as you propose in the comment