Merge pull request #27 from kaiiam/issue-18-docs-updates-maintenance

Documentation and DevOps cleanup/maintenance

.github/workflows/deploy-docs.yaml

@@ -35,16 +35,5 @@ jobs:
         run: |
           mkdir -p docs
           touch docs/.nojekyll
-          poetry run gen-doc -d docs src/mifc/schema/mifc.yaml
-          poetry run mkdocs gh-deploy
-#<<<<<<< ours
-#          cp src/docs/*md docs
-#          poetry run gen-doc -d docs src/mifc/schema/mifc.yaml
-#          poetry run mkdocs gh-deploy
-#=======
-#          make gendoc
-#          ([ ! -f docs/about.md ] && cp src/docs/about.md docs/) || true
-#          make mkd-gh-deploy
-#
-#...
-#>>>>>>> theirs
+          make gendoc
+          make mkd-gh-deploy

.github/workflows/test_pages_build.yaml

@@ -0,0 +1,45 @@
+name: Preview documentation build
+
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+
+concurrency: preview-${{ github.ref }}
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3.1.0
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python 3
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.9
+
+      - name: Install Poetry
+        uses: snok/install-poetry@v1
+        with:
+          version: 1.3.2
+
+      - name: Install dependencies
+        run: poetry install -E docs
+
+      - name: Build documentation
+        run: |
+          mkdir -p site
+          touch site/.nojekyll
+          make gendoc
+          poetry run mkdocs build -d site
+
+      - name: Deploy preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: site/
+          preview-branch: gh-pages

Makefile

@@ -23,6 +23,7 @@ DEST = project
 PYMODEL = $(SRC)/$(SCHEMA_NAME)/datamodel
 DOCDIR = docs
 EXAMPLEDIR = examples
+TEMPLATEDIR = doc-templates
 SHEET_MODULE = personinfo_enums
 SHEET_ID = $(LINKML_SCHEMA_GOOGLE_SHEET_ID)
 SHEET_TABS = $(LINKML_SCHEMA_GOOGLE_SHEET_TABS)
@@ -199,8 +200,10 @@ $(DOCDIR):
 	mkdir -p $@
 
 gendoc: $(DOCDIR)
-	cp -rf $(SRC)/docs/* $(DOCDIR) ; \
-	$(RUN) gen-doc ${GEN_DOC_ARGS} -d $(DOCDIR) $(SOURCE_SCHEMA_PATH)
+	cp $(SRC)/docs/*md $(DOCDIR) ; \
+	$(RUN) gen-doc -d $(DOCDIR) --template-directory $(SRC)/$(TEMPLATEDIR) $(SOURCE_SCHEMA_PATH)
+	mkdir -p $(DOCDIR)/javascripts
+	$(RUN) cp $(SRC)/scripts/*.js $(DOCDIR)/javascripts/
 
 testdoc: gendoc serve
 

mkdocs.yml

@@ -1,5 +1,5 @@
 ---
-site_name: "mifc"
+site_name: mifc
 theme:
   name: material
   # palette:
@@ -12,6 +12,13 @@ plugins:
   - mermaid2
   - mermaid2:
       version: 10.9.0
+markdown_extensions:
+  - admonition
+  - tables
+  - pymdownx.magiclink
+extra_javascript:
+  - https://unpkg.com/tablesort@5.3.0/dist/tablesort.min.js
+  - javascripts/tablesort.js
 nav:
   # - Home: home.md
   - Index: index.md

src/doc-templates/class.md.jinja2

@@ -0,0 +1,151 @@
+{%- 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 %}
+{% 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 %}
+
+URI: {{ gen.uri_link(element) }}
+
+
+{% if diagram_type == "er_diagram" %}
+```{{ gen.mermaid_directive() }}
+{{ gen.mermaid_diagram([element.name]) }}
+```
+{% elif diagram_type == "plantuml_class_diagram" %}
+```puml
+{{ gen.mermaid_diagram([element.name]) }}
+```
+{% else %}
+{% include "class_diagram.md.jinja2" %}
+{% 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 %}
+
+## Slots
+
+| 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
+
+| 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}} | {{ gen.link(usage.used) }} |
+{% endfor %}
+{% endif %}
+
+{% include "common_metadata.md.jinja2" %}
+
+
+{% if schemaview.get_mappings(element.name).items() -%}
+## Mappings
+
+| Mapping Type | Mapped Value |
+| ---  | ---  |
+{% for m, mt in schemaview.get_mappings(element.name).items() -%}
+{% if mt|length > 0 -%}
+| {{ 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 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,83 @@
+{% macro render_relationships(relationships) %}
+  {% for s in relationships -%}
+    {{ gen.name(element) }} : {{ gen.name(s) }}
+    {% if s.range not in gen.all_type_object_names() %}
+      {{ gen.name(element) }} --> "{{ gen.cardinality(s) }}" {{ gen.name(schemaview.get_element(s.range)) }} : {{ gen.name(s) }}
+    click {{ gen.name(schemaview.get_element(s.range)) }} href "../{{gen.name(schemaview.get_element(s.range))}}"
+    {% endif %}
+  {% endfor %}
+{% endmacro %}
+
+{% macro slot_relationships_count_fn(relationships) %}
+  {% set count = namespace(value=0) %}
+  {% for s in relationships -%}
+    {% if s.range not in gen.all_type_object_names() %}
+      {% set count.value = count.value + 1 %}
+    {% endif %}
+  {% endfor %}
+  {{ count.value }}
+{% endmacro %}
+
+{% set parent_count = schemaview.class_parents(element.name)|length %}
+{% set child_count = schemaview.class_children(element.name)|length %}
+{% set slot_relationships = schemaview.class_induced_slots(element.name)|sort(attribute='name') %}
+
+{% set slot_relationships_count = slot_relationships_count_fn(slot_relationships) %}
+
+{% if schemaview.class_induced_slots(element.name)|sort(attribute='name')|length < 60 and
+    parent_count|int < 20 and 
+    (child_count|int + slot_relationships_count|int) < 20
+%}
+{% if schemaview.class_parents(element.name) and schemaview.class_children(element.name) %}
+```{{ gen.mermaid_directive() }}
+classDiagram
+  class {{ gen.name(element) }}
+  click {{ gen.name(element) }} href "../{{gen.name(element)}}"
+    {% for s in schemaview.class_parents(element.name)|sort(attribute='name') -%}
+      {{ gen.name(schemaview.get_element(s)) }} <|-- {{ gen.name(element) }}
+      click {{ gen.name(schemaview.get_element(s)) }} href "../{{gen.name(schemaview.get_element(s))}}"
+    {% endfor %}
+
+    {% for s in schemaview.class_children(element.name)|sort(attribute='name') -%}
+      {{ gen.name(element) }} <|-- {{ gen.name(schemaview.get_element(s)) }}
+      click {{ gen.name(schemaview.get_element(s)) }} href "../{{gen.name(schemaview.get_element(s))}}"
+    {% endfor %}
+
+    {{ render_relationships(slot_relationships) }}
+```
+{% elif schemaview.class_parents(element.name) %}
+```{{ gen.mermaid_directive() }}
+classDiagram
+  class {{ gen.name(element) }}
+  click {{ gen.name(element) }} href "../{{gen.name(element)}}"
+    {% for s in schemaview.class_parents(element.name)|sort(attribute='name') -%}
+      {{ gen.name(schemaview.get_element(s)) }} <|-- {{ gen.name(element) }}
+      click {{ gen.name(schemaview.get_element(s)) }} href "../{{gen.name(schemaview.get_element(s))}}"
+    {% endfor %}
+
+    {{ render_relationships(slot_relationships) }}
+```
+{% elif schemaview.class_children(element.name) %}
+```{{ gen.mermaid_directive() }}
+classDiagram
+  class {{ gen.name(element) }}
+  click {{ gen.name(element) }} href "../{{gen.name(element)}}"
+    {% for s in schemaview.class_children(element.name)|sort(attribute='name') -%}
+      {{ gen.name(element) }} <|-- {{ gen.name(schemaview.get_element(s)) }}
+      click {{ gen.name(schemaview.get_element(s)) }} href "../{{gen.name(schemaview.get_element(s))}}"
+    {% endfor %}
+
+    {{ render_relationships(slot_relationships) }}
+```
+{% else %}
+```{{ gen.mermaid_directive() }}
+classDiagram
+  class {{ gen.name(element) }}
+  click {{ gen.name(element) }} href "../{{gen.name(element)}}"
+    {{ render_relationships(slot_relationships) }}
+```
+{% endif %}
+{% else %}
+!!! note
+    Mermaid class diagram too large to render.
+{% endif %}