From ec17c561ba97a805d7eb01f335799dd9529c634e Mon Sep 17 00:00:00 2001 From: Sujay Patil Date: Wed, 10 Jul 2024 16:09:03 -0700 Subject: [PATCH 1/5] clean up docs deploy Action and add docs preview Action --- .github/workflows/deploy-docs.yaml | 15 ++------- .github/workflows/deploy-docs.yaml.rej | 7 ---- .github/workflows/test_pages_build.yaml | 45 +++++++++++++++++++++++++ 3 files changed, 47 insertions(+), 20 deletions(-) delete mode 100644 .github/workflows/deploy-docs.yaml.rej create mode 100644 .github/workflows/test_pages_build.yaml diff --git a/.github/workflows/deploy-docs.yaml b/.github/workflows/deploy-docs.yaml index 7508696..fa9c45e 100644 --- a/.github/workflows/deploy-docs.yaml +++ b/.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 \ No newline at end of file diff --git a/.github/workflows/deploy-docs.yaml.rej b/.github/workflows/deploy-docs.yaml.rej deleted file mode 100644 index 936ce1c..0000000 --- a/.github/workflows/deploy-docs.yaml.rej +++ /dev/null @@ -1,7 +0,0 @@ -diff a/.github/workflows/deploy-docs.yaml b/.github/workflows/deploy-docs.yaml (rejected hunks) -@@ -31,5 +38,3 @@ jobs: - make gendoc - ([ ! -f docs/about.md ] && cp src/docs/about.md docs/) || true - make mkd-gh-deploy -- --... diff --git a/.github/workflows/test_pages_build.yaml b/.github/workflows/test_pages_build.yaml new file mode 100644 index 0000000..b6e51b8 --- /dev/null +++ b/.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 From 5e8e61c31a49b34c061445dff6934effcdcbff23 Mon Sep 17 00:00:00 2001 From: Sujay Patil Date: Wed, 10 Jul 2024 16:11:41 -0700 Subject: [PATCH 2/5] jinja templates for customizing documentation pages --- src/doc-templates/class.md.jinja2 | 151 ++++++++++++++++++++ src/doc-templates/class_diagram.md.jinja2 | 83 +++++++++++ src/doc-templates/common_metadata.md.jinja2 | 63 ++++++++ src/doc-templates/index.md.jinja2 | 60 ++++++++ 4 files changed, 357 insertions(+) create mode 100644 src/doc-templates/class.md.jinja2 create mode 100644 src/doc-templates/class_diagram.md.jinja2 create mode 100644 src/doc-templates/common_metadata.md.jinja2 create mode 100644 src/doc-templates/index.md.jinja2 diff --git a/src/doc-templates/class.md.jinja2 b/src/doc-templates/class.md.jinja2 new file mode 100644 index 0000000..38d6147 --- /dev/null +++ b/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 -%} +  or 
+ {%- 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 %} + +{% 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) }}
{{ 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) }}
{{ 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 + + + +### Direct + +
+```yaml +{{gen.yaml(element)}} +``` +
+ +### Induced + +
+```yaml +{{gen.yaml(element, inferred=True)}} +``` +
+ +{%- if footer -%} +{{footer}} +{%- endif -%} \ No newline at end of file diff --git a/src/doc-templates/class_diagram.md.jinja2 b/src/doc-templates/class_diagram.md.jinja2 new file mode 100644 index 0000000..52a8064 --- /dev/null +++ b/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 %} diff --git a/src/doc-templates/common_metadata.md.jinja2 b/src/doc-templates/common_metadata.md.jinja2 new file mode 100644 index 0000000..c7949e4 --- /dev/null +++ b/src/doc-templates/common_metadata.md.jinja2 @@ -0,0 +1,63 @@ +{% 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.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 %} \ No newline at end of file diff --git a/src/doc-templates/index.md.jinja2 b/src/doc-templates/index.md.jinja2 new file mode 100644 index 0000000..eaad3de --- /dev/null +++ b/src/doc-templates/index.md.jinja2 @@ -0,0 +1,60 @@ +# {% if schema.title %}{{ schema.title }}{% else %}{{ schema.name }}{% endif %} + +{% if schema.description %}{{ schema.description }}{% endif %} + +URI: {{ schema.id }} + +{% 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() -%} +| {{ " "|safe*u*8 }}{{ gen.link(schemaview.get_class(v)) }} | {{ 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 + +| Slot | Description | +| --- | --- | +{% for s in gen.all_slot_objects()|sort(attribute=sort_by) -%} +| {{gen.link(s)}} | {{s.description|enshorten}} | +{% endfor %} + +## Enumerations + +| Enumeration | Description | +| --- | --- | +{% for e in gen.all_enum_objects()|sort(attribute=sort_by) -%} +| {{gen.link(e)}} | {{e.description|enshorten}} | +{% endfor %} + +## Types + +| Type | Description | +| --- | --- | +{% for t in gen.all_type_objects()|sort(attribute=sort_by) -%} +| {{gen.link(t)}} | {{t.description|enshorten}} | +{% endfor %} + +## Subsets + +| Subset | Description | +| --- | --- | +{% for ss in schemaview.all_subsets().values()|sort(attribute='name') -%} +| {{gen.link(ss)}} | {{ss.description|enshorten}} | +{% endfor %} From f6003a0aac49b634ee807e94cc9869ce298e57d7 Mon Sep 17 00:00:00 2001 From: Sujay Patil Date: Wed, 10 Jul 2024 16:11:57 -0700 Subject: [PATCH 3/5] add JS for table sorting --- src/scripts/tablesort.js | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 src/scripts/tablesort.js diff --git a/src/scripts/tablesort.js b/src/scripts/tablesort.js new file mode 100644 index 0000000..c29295d --- /dev/null +++ b/src/scripts/tablesort.js @@ -0,0 +1,6 @@ +document$.subscribe(function () { + var tables = document.querySelectorAll("article table:not([class])"); + tables.forEach(function (table) { + new Tablesort(table); + }); + }); \ No newline at end of file From 0bbf1774d041756c5722c62f44bf8d1168b58b82 Mon Sep 17 00:00:00 2001 From: Sujay Patil Date: Wed, 10 Jul 2024 16:12:56 -0700 Subject: [PATCH 4/5] documentation targets related modifications to Makefile and mkdocs --- Makefile | 9 +++++++-- mkdocs.yml | 9 ++++++++- 2 files changed, 15 insertions(+), 3 deletions(-) diff --git a/Makefile b/Makefile index 058c8a3..2f17805 100644 --- a/Makefile +++ b/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,12 @@ $(DOCDIR): mkdir -p $@ gendoc: $(DOCDIR) - cp -rf $(SRC)/docs/* $(DOCDIR) ; \ - $(RUN) gen-doc ${GEN_DOC_ARGS} -d $(DOCDIR) $(SOURCE_SCHEMA_PATH) + # added copying of images and renaming of TEMP.md + cp $(SRC)/docs/*md $(DOCDIR) ; \ + cp -r $(SRC)/docs/images $(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 diff --git a/mkdocs.yml b/mkdocs.yml index 2a1e7ea..a81dfe4 100644 --- a/mkdocs.yml +++ b/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 From bd3d9beecf77585da025fadea96b525d44618dad Mon Sep 17 00:00:00 2001 From: Sujay Patil Date: Wed, 10 Jul 2024 16:15:46 -0700 Subject: [PATCH 5/5] remove step that copies images/ from src/doc in make gendoc --- Makefile | 2 -- 1 file changed, 2 deletions(-) diff --git a/Makefile b/Makefile index 2f17805..f0b79d4 100644 --- a/Makefile +++ b/Makefile @@ -200,9 +200,7 @@ $(DOCDIR): mkdir -p $@ gendoc: $(DOCDIR) - # added copying of images and renaming of TEMP.md cp $(SRC)/docs/*md $(DOCDIR) ; \ - cp -r $(SRC)/docs/images $(DOCDIR) ; \ $(RUN) gen-doc -d $(DOCDIR) --template-directory $(SRC)/$(TEMPLATEDIR) $(SOURCE_SCHEMA_PATH) mkdir -p $(DOCDIR)/javascripts $(RUN) cp $(SRC)/scripts/*.js $(DOCDIR)/javascripts/