INCATools / INCATools/ontology-development-kit
Properly document `use_custom_import_module`
- 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
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