Merge pull request #81 from INCATools/phenio-test

Adding phenio-test

.github/workflows/deploy_documentation.yml

@@ -53,4 +53,5 @@ jobs:
         mkdir docs
         touch docs/.nojekyll
         cp -r src/docs/* docs/
-        make deploy-gh-doc
+        make gendoc
+        make mkd-gh-deploy

Makefile

@@ -21,6 +21,19 @@ STAGED_ONTOLOGIES = $(patsubst %, stage/%.db.gz, $(ALL_ONTS))
 
 TEST_ONTOLOGIES = go-nucleus robot-example
 
+# environment variables
+include config.env
+
+GEN_PARGS =
+ifdef LINKML_GENERATORS_PROJECT_ARGS
+GEN_PARGS = ${LINKML_GENERATORS_PROJECT_ARGS}
+endif
+
+GEN_DARGS =
+ifdef LINKML_GENERATORS_MARKDOWN_ARGS
+GEN_DARGS = ${LINKML_GENERATORS_MARKDOWN_ARGS}
+endif
+
 
 include ontologies.Makefile
 
@@ -175,16 +188,18 @@ include ontologies.Makefile
 
 MODULES = rdf owl obo omo relation_graph semsql
 
-GENDOC_ARGS = --no-mergeimports -d docs --template-directory docgen-templates
+GENDOC_ARGS = -d docs --template-directory docgen-templates
 
 # TODO: markdown gen should make modular output
 markdown-%: $(YAML_DIR)/%.yaml
 	$(RUN) gen-doc $(GENDOC_ARGS) $< && mv docs/index.md docs/$*_index.md
 markdown: $(patsubst %, markdown-%, $(MODULES))
 	$(RUN) gen-doc $(GENDOC_ARGS) $(YAML_DIR)/semsql.yaml
 
+gendoc: markdown
+
 gen-project: $(YAML_DIR)/semsql.yaml
-	$(RUN) gen-project $< -d project
+	$(RUN) gen-project  ${GEN_PARGS} $< -d project
 
 # Create SQL Create Table statements from linkml
 # 1. first use generic ddl generation
@@ -228,6 +243,24 @@ s3-version:
 s3-deploy-%: stage/%.db.gz
 	aws s3 cp $< s3://bbop-sqlite/$*.db.gz --acl public-read
 
+
+# Test documentation locally
+serve: mkd-serve
+
+# Python datamodel
+$(PYMODEL):
+	mkdir -p $@
+
+
+$(DOCDIR):
+	mkdir -p $@
+
+testdoc: gendoc serve
+
+MKDOCS = $(RUN) mkdocs
+mkd-%:
+	$(MKDOCS) $*
+
 ################################################
 #### Commands for building the Docker image ####
 ################################################

config.env

@@ -0,0 +1,8 @@
+LINKML_GENERATORS_PROJECT_ARGS=--config-file config.yaml
+
+### Extra layer of configuration for Makefile beyond
+### what 'gen-project --config-file config.yaml' provides.
+### Uncomment and set environment variables as needed.
+
+# LINKML_GENERATORS_MARKDOWN_ARGS=--no-mergeimports
+

docgen-templates/class.md.jinja2

@@ -1,57 +1,59 @@
-# Class: {{ gen.name(element) }}
+{%- if element.title %}
+    {%- set title = element.title ~ ' (' ~ element.name ~ ')' -%}
+{%- else %}
+    {%- if gen.use_class_uris -%}
+        {%- set title = element.name -%}
+    {%- else -%}
+        {%- set title = gen.name(element) -%}
+    {%- endif -%}
+{%- endif -%}
+
+{% macro compute_range(slot) -%}
+    {%- if slot.any_of or slot.exactly_one_of -%}
+        {%- for subslot_range in schemaview.slot_range_as_union(slot) -%}
+            {{ gen.link(subslot_range) }}
+            {%- if not loop.last -%}
+                &nbsp;or&nbsp;<br />
+            {%- endif -%}
+        {%- endfor -%}
+    {%- else -%}
+        {{ gen.link(slot.range) }}
+    {%- endif -%}
+{% endmacro %}
+
+# Class: {{ title }}
 
 {%- if header -%}
 {{header}}
 {%- endif -%}
 
 
 {% if element.description %}
-_{{ element.description }}_
+{% set element_description_lines = element.description.split('\n') %}
+{% for element_description_line in element_description_lines %}
+_{{ element_description_line }}_
+{% endfor %}
 {% endif %}
 
 {% if element.abstract %}
 * __NOTE__: this is an abstract class and should not be instantiated directly
 {% endif %}
-{% if element.mixin %}
-* __NOTE__: this is a mixin class intended to be used in combination with other classes, and not used directly
-{% endif %}
 
 URI: {{ gen.uri_link(element) }}
 
 
-
-{% if schemaview.class_parents(element.name) %}
+{% if diagram_type == "er_diagram" %}
 ```{{ gen.mermaid_directive() }}
- classDiagram
-      {% for s in schemaview.class_parents(element.name)|sort(attribute='name') -%}
-        {{ gen.name(schemaview.get_element(s)) }} <|-- {{ gen.name(element) }}
-      {% endfor %}
-      {% for s in schemaview.class_induced_slots(element.name)|sort(attribute='name') -%}
-        {{ gen.name(element) }} : {{gen.name(s)}}
-      {% endfor %}
-
+{{ gen.mermaid_diagram([element.name]) }}
 ```
-{% elif schemaview.class_children(element.name)  %}
-```{{ gen.mermaid_directive() }}
- classDiagram
-      {% for s in schemaview.class_children(element.name)|sort(attribute='name') -%}
-        {{ gen.name(element) }} <|-- {{ gen.name(schemaview.get_element(s)) }}
-      {% endfor %}
-      {% for s in schemaview.class_induced_slots(element.name)|sort(attribute='name') -%}
-        {{ gen.name(element) }} : {{gen.name(s)}}
-      {% endfor %}
+{% elif diagram_type == "plantuml_class_diagram" %}
+```puml
+{{ gen.mermaid_diagram([element.name]) }}
 ```
 {% else %}
-```{{ gen.mermaid_directive() }}
- classDiagram
-    class {{ gen.name(element) }}
-      {% for s in schemaview.class_induced_slots(element.name)|sort(attribute='name') -%}
-        {{ gen.name(element) }} : {{gen.name(s)}}
-      {% endfor %}
-```
+{% include "class_diagram.md.jinja2" %}
 {% endif %}
 
-
 {% if schemaview.class_parents(element.name) or schemaview.class_children(element.name, mixins=False) %}
 
 ## Usage
@@ -68,19 +70,36 @@ SELECT * FROM {{element.name}};
 
 ## Slots
 
-| Name | Cardinality and Range  | Description  |
-| ---  | ---  | --- |
-{% for s in schemaview.class_induced_slots(element.name) -%}
-| {{gen.link(s)}} | {{ gen.cardinality(s) }} <br/> {{gen.link(s.range)}}  | {{s.description|enshorten}}  |
+| Name | Cardinality and Range | Description | Inheritance |
+| ---  | --- | --- | --- |
+{% if gen.get_direct_slots(element)|length > 0 %}
+{%- for slot in gen.get_direct_slots(element) -%}
+| {{ gen.link(slot) }} | {{ gen.cardinality(slot) }} <br/> {{ compute_range(slot) }} | {{ slot.description|enshorten }} | direct |
+{% endfor -%}
+{% endif -%}
+{% if gen.get_indirect_slots(element)|length > 0 %}
+{%- for slot in gen.get_indirect_slots(element) -%}
+| {{ gen.link(slot) }} | {{ gen.cardinality(slot) }} <br/> {{ compute_range(slot) }} | {{ slot.description|enshorten }} | {{ gen.links(gen.get_slot_inherited_from(element.name, slot.name))|join(', ') }} |
+{% endfor -%}
+{% endif %}
+
+{% if schemaview.is_mixin(element.name) %}
+## Mixin Usage
+
+| mixed into | description |
+| --- | --- |
+{% for c in schemaview.class_children(element.name, is_a=False) -%}
+| {{ gen.link(c) }} | {{ schemaview.get_class(c).description|enshorten }} |
 {% endfor %}
+{% endif %}
 
+{% if schemaview.usage_index().get(element.name) %}
 ## Usages
 
-{% if schemaview.usage_index().get(element.name) %}
 | used by | used in | type | used |
 | ---  | --- | --- | --- |
 {% for usage in schemaview.usage_index().get(element.name) -%}
-| {{gen.link(usage.used_by)}} | {{gen.link(usage.slot)}} | {{usage.metaslot}} | {{usage.used }} |
+| {{gen.link(usage.used_by)}} | {{gen.link(usage.slot)}} | {{usage.metaslot}} | {{ gen.link(usage.used) }} |
 {% endfor %}
 {% endif %}
 
@@ -128,14 +147,25 @@ This class has a SQL view definition:
 | ---  | ---  |
 {% for m, mt in schemaview.get_mappings(element.name).items() -%}
 {% if mt|length > 0 -%}
-| {{ m }} | {{ mt }} |
+| {{ m }} | {{ mt|join(', ') }} |
 {% endif -%}
 {% endfor %}
 
 {% endif -%}
 
+{% if gen.example_object_blobs(element.name) -%}
+## Examples
+{% for name, blob in gen.example_object_blobs(element.name) -%}
+### Example: {{name}}
+
+```yaml
+{{ blob }}
+```
+{% endfor %}
+{% endif %}
+
 
-## LinkML Specification
+## LinkML Source
 
 <!-- TODO: investigate https://stackoverflow.com/questions/37606292/how-to-create-tabbed-code-blocks-in-mkdocs-or-sphinx -->
 
@@ -157,4 +187,4 @@ This class has a SQL view definition:
 
 {%- if footer -%}
 {{footer}}
-{%- endif -%}
+{%- endif -%}

docgen-templates/common_metadata.md.jinja2

@@ -1,3 +1,22 @@
+{% if element.aliases %}
+## Aliases
+
+{% for alias in element.aliases %}
+* {{ alias }}
+{%- endfor %}
+{% endif %}
+
+
+{% if element.examples %}
+## Examples
+
+| Value |
+| --- |
+{% for x in element.examples -%}
+| {{ x.value }} |
+{% endfor %}
+{% endif -%}
+
 {% if element.comments -%}
 ## Comments
 
@@ -14,6 +33,14 @@
 {% endfor %}
 {% endif -%}
 
+{% if element.see_also -%}
+## See Also
+
+{% for x in element.see_also -%}
+* {{ gen.uri_link(x) }}
+{% endfor %}
+{% endif -%}
+
 ## Identifier and Mapping Information
 
 {% if element.id_prefixes %}
@@ -33,7 +60,9 @@ Instances of this class *should* have identifiers with one of the following pref
 | property | value |
 | --- | --- |
 {% for a in element.annotations -%}
-| {{a}} | {{ element.annotations[a].value }} |
+{%- if a|string|first != '_' -%}
+| {{ a }} | {{ element.annotations[a].value }} |
+{%- endif -%}
 {% endfor %}
 {% endif %}
 

docgen-templates/enum.md.jinja2

@@ -1,24 +1,40 @@
-# {{ gen.name(element) }}
+# Enum: {{ gen.name(element) }}
 
-{{ element.description }}
+{% if element.description %}
+{% set element_description_lines = element.description.split('\n') %}
+{% for element_description_line in element_description_lines %}
+_{{ element_description_line }}_
+{% endfor %}
+{% endif %}
 
-URI: {{ gen.uri(element) }}
+URI: {{ gen.link(element) }}
 
 {% if element.permissible_values -%}
 ## Permissible Values
 
-| Value | Meaning | Description | Info |
-| --- | --- | --- | --- |
+| Value | Meaning | Description |
+| --- | --- | --- |
 {% for pv in element.permissible_values.values() -%}
-| {{pv.text}} | {{pv.meaning}} | {{pv.description|enshorten}} | |
+| {{pv.text}} | {{pv.meaning}} | {{pv.description|enshorten}} |
 {% endfor %}
 {% else %}
 _This is a dynamic enum_
 {% endif %}
 
+{% set slots_for_enum = schemaview.get_slots_by_enum(element.name) %}
+{% if slots_for_enum is defined and slots_for_enum|length > 0 -%}
+## Slots
+
+| Name | Description |
+| ---  | --- |
+{% for s in schemaview.get_slots_by_enum(element.name) -%}
+| {{gen.link(s)}} | {{s.description|enshorten}} |
+{% endfor %}
+{% endif %}
+
 {% include "common_metadata.md.jinja2" %}
 
-## Schema
+## LinkML Source
 
 <details>
 ```yaml

docgen-templates/index.md.jinja2

@@ -1,17 +1,35 @@
 # {% if schema.title %}{{ schema.title }}{% else %}{{ schema.name }}{% endif %}
 
-{{ schema.description }}
+{% if schema.description %}{{ schema.description }}{% endif %}
 
 URI: {{ schema.id }}
+
 Name: {{ schema.name }}
 
+{% if include_top_level_diagram %}
+
+## Schema Diagram
+
+```{{ gen.mermaid_directive() }}
+{{ gen.mermaid_diagram() }}
+```
+{% endif %}
+
 ## Classes
 
 | Class | Description |
 | --- | --- |
+{% if gen.hierarchical_class_view -%}
+{% for u, v in gen.class_hierarchy_as_tuples() -%}
+{%- set link = gen.link(schemaview.get_class(v)) -%}
+{%- set hi = "**" if schemaview.get_class(v, imports=False) else "*" -%}
+| {{ " "|safe*u*8 }}{{ hi }}{{ link }}{{ hi }} | {{ schemaview.get_class(v).description }} |
+{% endfor %}
+{% else -%}
 {% for c in gen.all_class_objects()|sort(attribute=sort_by) -%}
 | {{gen.link(c)}} | {{c.description|enshorten}} |
 {% endfor %}
+{% endif %}
 
 ## Slots