Merge pull request #23 from GenomicsStandardsConsortium/mixs-template…

…s-migration

Custom documentation pages for MIXS schema

Makefile

@@ -15,6 +15,8 @@ SRC = src
 DEST = project
 PYMODEL = $(SRC)/$(SCHEMA_NAME)/datamodel
 DOCDIR = docs
+TEMPLATEDIR = $(SRC)/doc-templates
+TERM_LIST_FILE = $(DOCDIR)/term_list.md
 EXAMPLEDIR = examples
 SHEET_MODULE = personinfo_enums
 SHEET_ID = $(shell ${SHELL} ./utils/get-value.sh google_sheet_id)
@@ -157,7 +159,10 @@ $(DOCDIR):
 
 gendoc: $(DOCDIR)
 	cp $(SRC)/docs/*md $(DOCDIR) ; \
-	$(RUN) gen-doc ${GEN_DARGS} -d $(DOCDIR) $(SOURCE_SCHEMA_PATH)
+	$(RUN) gen-doc ${GEN_DARGS} -d $(DOCDIR) $(SOURCE_SCHEMA_PATH) --template-directory $(TEMPLATEDIR)
+	$(RUN) python $(SRC)/scripts/term_list_generator.py $(TERM_LIST_FILE)
+	mkdir -p $(DOCDIR)/javascripts
+	$(RUN) cp $(SRC)/scripts/javascripts/* $(DOCDIR)/javascripts/
 
 testdoc: gendoc serve
 

mkdocs.yml

@@ -10,13 +10,20 @@ theme:
 plugins:
   - search
   - mermaid2
+markdown_extensions:
+  - tables
+extra_javascript:
+  - https://unpkg.com/[email protected]/dist/tablesort.min.js
+  - javascripts/tablesort.js
 nav:
   # - Home: home.md
   - Index: index.md
-  - About: about.md
+  - Full term table: term_list.md
 site_url: https://GenomicsStandardsConsortium.github.io/mixs-6-2-for-merge
 repo_url: https://github.com/GenomicsStandardsConsortium/mixs-6-2-for-merge
 
+docs_dir: docs
+
 # Uncomment this block to enable use of Google Analytics.
 # Replace the property value with your own ID.
 # extra:

src/doc-templates/class.md.jinja2

@@ -0,0 +1,67 @@
+# Class: {{ gen.name(element) }}
+
+{%- if header -%}
+{{header}}
+{%- endif -%}
+
+
+{% if 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 schemaview.class_parents(element.name) or schemaview.class_children(element.name, mixins=False) %}
+
+## Inheritance
+{{ gen.inheritance_tree(element, mixins=True) }}
+{% else %}
+<!-- no inheritance hierarchy -->
+{% endif %}
+
+## Terms
+
+| 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/> {{ gen.link(slot.range) }} | {{ 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/> {{ gen.link(slot.range) }} | {{ slot.description|enshorten }} | {{ gen.links(gen.get_slot_inherited_from(element.name, slot.name))|join(', ') }} |
+{% endfor -%}
+{% endif %}
+
+{% include "common_metadata.md.jinja2" %}
+
+
+## LinkML Source
+
+<!-- TODO: investigate https://stackoverflow.com/questions/37606292/how-to-create-tabbed-code-blocks-in-mkdocs-or-sphinx -->
+
+### Direct
+
+<details>
+```yaml
+{{gen.yaml(element)}}
+```
+</details>
+
+### Induced
+
+<details>
+```yaml
+{{gen.yaml(element, inferred=True)}}
+```
+</details>
+
+{%- if footer -%}
+{{footer}}
+{%- endif -%}

src/doc-templates/class_diagram.md.jinja2

@@ -0,0 +1,59 @@
+{% if schemaview.class_parents(element.name) and schemaview.class_children(element.name) %}
+```{{ gen.mermaid_directive() }}
+ classDiagram
+    class {{ gen.name(element) }}
+      {% 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_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)}}
+        {% if s.range not in gen.all_type_object_names() %}
+          {{ gen.name(element) }} --|> {{ s.range }} : {{ gen.name(s) }}
+        {% endif %}
+      {% endfor %}
+```
+{% elif schemaview.class_parents(element.name) %}
+```{{ gen.mermaid_directive() }}
+ classDiagram
+    class {{ gen.name(element) }}
+      {% 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)}}
+        {% if s.range not in gen.all_type_object_names() %}
+          {{ gen.name(element) }} --|> {{ s.range }} : {{ gen.name(s) }}
+        {% endif %}
+      {% endfor %}
+```
+{% elif schemaview.class_children(element.name)  %}
+```{{ gen.mermaid_directive() }}
+ classDiagram
+    class {{ gen.name(element) }}
+      {% 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)}}
+        {% if s.range not in gen.all_type_object_names() %}
+          {{ gen.name(element) }} --|> {{ s.range }} : {{ gen.name(s) }}
+        {% endif %}
+      {% endfor %}
+```
+{% 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)}}
+        {% if s.range not in gen.all_type_object_names() %}
+          {{ gen.name(element) }} --|> {{ s.range }} : {{ gen.name(s) }}
+        {% endif %}
+      {% endfor %}
+```
+{% endif %}

src/doc-templates/common_metadata.md.jinja2

@@ -0,0 +1,78 @@
+{% 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
+
+{% for x in element.comments -%}
+* {{x}}
+{% endfor %}
+{% endif -%}
+
+{% if element.todos -%}
+## TODOs
+
+{% for x in element.todos -%}
+* {{x}}
+{% 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 %}
+### Valid ID Prefixes
+
+Instances of this class *should* have identifiers with one of the following prefixes:
+{% for p in element.id_prefixes %}
+* {{p}}
+{% endfor %}
+
+{% endif %}
+
+
+{% if element.annotations %}
+### Annotations
+
+| property | value |
+| --- | --- |
+{% for a in element.annotations -%}
+{%- if a|string|first != '_' -%}
+| {{ a }} | {{ element.annotations[a].value }} |
+{%- endif -%}
+{% endfor %}
+{% endif %}
+
+{% if element.from_schema or element.imported_from %}
+### Schema Source
+
+{% if element.from_schema %}
+* from schema: {{ element.from_schema }}
+{% endif %}
+{% if element.imported_from %}
+* imported from: {{ element.imported_from }}
+{% endif %}
+{% endif %}

src/doc-templates/enum.md.jinja2

@@ -0,0 +1,44 @@
+# Enum: {{ gen.name(element) }}
+
+{% 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_link(element) }}
+
+{% if element.permissible_values -%}
+## Permissible Values
+
+| Value | Description |
+| --- | --- |
+{% for pv in element.permissible_values.values() -%}
+| {{pv.text}} | {{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 -%}
+## Terms
+
+| 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" %}
+
+## LinkML Source
+
+<details>
+```yaml
+{{gen.yaml(element)}}
+```
+</details>
+

src/doc-templates/index.md.jinja2

@@ -0,0 +1,53 @@
+#  {{ schema.name }}
+
+{{ schema.description }}
+
+URI: <a href={{ schema.id }}>{{ schema.id }}</a>
+
+## Checklists
+
+| Checklist | Description |
+{% for c in schemaview.all_classes().values() -%}
+{%- if c.is_a == "Checklist" -%}
+| --- | --- |
+| {{ gen.link(c) }} | {{ c.description }} |
+{%- endif -%}
+{% endfor %}
+
+## Extensions
+
+| Extension | Description |
+{% for c in schemaview.all_classes().values() -%}
+{%- if c.is_a == "Extension" -%}
+| --- | --- |
+| {{ gen.link(c) }} | {{ c.description }} |
+{%- endif -%}
+{% endfor %}
+
+## Combinations
+
+| Combination | Description |
+{% for c in schemaview.all_classes().values() -%}
+{% if c.mixins and c.is_a -%}
+| --- | --- |
+| {{ gen.link(c) }} | {{ c.description }} |
+{%- endif -%}
+{% endfor %}
+
+## Subsets
+
+| Subset | Description |
+| --- | --- |
+{% for ss in schemaview.all_subsets().values()|sort(attribute='name') -%}
+| {{gen.link(ss)}} | {{ss.description|enshorten}} |
+{% endfor %}
+
+## Enumerations
+
+| Enumeration | Description |
+| --- | --- |
+{% for e in gen.all_enum_objects()|sort(attribute=sort_by) -%}
+| {{gen.link(e)}} | {{e.description|enshorten}} |
+{% endfor %}
+
+