INCATools / INCATools/ontology-development-kit

Properly document `use_custom_import_module`

Open
#1,365 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
Dockerfile
Stars
375
Forks
69
Avg merge
3d 5h
Merged PRs (30d)
7

Description

The ODK allows its user to ”enable the use of a custom import module”:

```python
use_custom_import_module: bool = False
"""Enables the use of a custom import module.

If true, this adds a custom import module which is managed through a
ROBOT template. This can also be used to manage your module seed.
"""
```

This option triggers the production of two additional files: `$(IMPORT_MODULE_SIGNATURE)` (`tmp/external_import_terms.txt`) and `$(IMPORT_MODULE)` (`imports/external_import.owl`).

However only the `$(IMPORT_MODULE_SIGNATURE)` is effectively used for anything (it is added to the general import seed in `tmp/seed.txt`). The sole purpose of `$(IMPORT_MODULE)` seems to be the computation of the `$(IMPORT_MODULE_SIGNATURE)`, [here](https://github.com/INCATools/odkcore/blob/f068fea1fbd574c4b787dfd229b8916b676223ed/src/incatools/odk/templates/src/ontology/Makefile.jinja2#L526):

```Makefile
$(IMPORT_MODULE): $(IMPORT_MODULE_TEMPLATE) | $(TMPDIR)
$(ROBOT) template --template $< {% if project.use_context %}--add-prefixes $(CONTEXT_FILE) {% endif %}\
--ontology-iri "$(ONTBASE)/external_import.owl" \
convert -f {{ project.import_component_format|default('ofn') }} \
--output $@

$(IMPORT_MODULE_SIGNATURE): $(IMPORT_MODULE) | $(TMPDIR)
$(ROBOT) query -f csv -i $< --query ../sparql/terms.sparql $@.tmp &&\
cat $@.tmp | sort | uniq > $@
```

The `$(IMPORT_MODULE_SIGNATURE)` rule is the **only** place where the `$(IMPORT_MODULE)` file is used for anything. The file is created in the `imports` directory but never referenced from anywhere. It is _not_ imported into the `-edit` file, _not_ referenced in the XML catalog, _not_ included in the `$(IMPORT_FILES)` (and therefore not released with the other import modules, when `release_imports` is enabled), _not_ merged in any output artefact.

So: does that file has any other purpose than serving to compute the `$(IMPORT_MODULE_SIGNATURE)`? Because if not, the two rules above can be merged into a single one:

```Makefile
$(IMPORT_MODULE_SIGNATURE): $(IMPORT_MODULE_TEMPLATE) | $(TMPDIR)
$(ROBOT) template --template $< \
query --format csv --query $(SPARQLDIR)/terms.sparql $@
```

where we instantiate the template and then run the `terms.sparql` query on the resulting ontology, without ever having to write an intermediate file (and thus saving one more call to ROBOT).

Contributor guide

Open the contributing guide

Research direction

Start with src/incatools/odk/templates/src/ontology/Makefile.jinja2 and search for use_custom_import_module, IMPORT_MODULE, and IMPORT_MODULE_SIGNATURE. Read the surrounding build rules and related user-facing documentation, then document the generated files, their roles, and the option's behavior. Done means a newcomer can understand whether the intermediate import file has an independent purpose.

Written by the indexing model from the issue text.

Assessment

Domain
build-system, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
58/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.