Skip to content

Commit 9a95f2e

Browse files
cmungallcmungall
committed
update
1 parent 763819d commit 9a95f2e

35 files changed

+5631
-3205
lines changed

‎.github/workflows/deploy_documentation.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,4 +53,5 @@ jobs:
5353
mkdir docs
5454
touch docs/.nojekyll
5555
cp -r src/docs/* docs/
56-
make deploy-gh-doc
56+
make gendoc
57+
make mkd-gh-deploy

‎Makefile‎

Lines changed: 35 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,19 @@ STAGED_ONTOLOGIES = $(patsubst %, stage/%.db.gz, $(ALL_ONTS))
2121

2222
TEST_ONTOLOGIES = go-nucleus robot-example
2323

24+
# environment variables
25+
include config.env
26+
27+
GEN_PARGS =
28+
ifdef LINKML_GENERATORS_PROJECT_ARGS
29+
GEN_PARGS = ${LINKML_GENERATORS_PROJECT_ARGS}
30+
endif
31+
32+
GEN_DARGS =
33+
ifdef LINKML_GENERATORS_MARKDOWN_ARGS
34+
GEN_DARGS = ${LINKML_GENERATORS_MARKDOWN_ARGS}
35+
endif
36+
2437

2538
include ontologies.Makefile
2639

@@ -175,16 +188,18 @@ include ontologies.Makefile
175188

176189
MODULES = rdf owl obo omo relation_graph semsql
177190

178-
GENDOC_ARGS = --no-mergeimports -d docs --template-directory docgen-templates
191+
GENDOC_ARGS = -d docs --template-directory docgen-templates
179192

180193
# TODO: markdown gen should make modular output
181194
markdown-%: $(YAML_DIR)/%.yaml
182195
$(RUN) gen-doc $(GENDOC_ARGS) $< && mv docs/index.md docs/$*_index.md
183196
markdown: $(patsubst %, markdown-%, $(MODULES))
184197
$(RUN) gen-doc $(GENDOC_ARGS) $(YAML_DIR)/semsql.yaml
185198

199+
gendoc: markdown
200+
186201
gen-project: $(YAML_DIR)/semsql.yaml
187-
$(RUN) gen-project $< -d project
202+
$(RUN) gen-project ${GEN_PARGS} $< -d project
188203

189204
# Create SQL Create Table statements from linkml
190205
# 1. first use generic ddl generation
@@ -228,6 +243,24 @@ s3-version:
228243
s3-deploy-%: stage/%.db.gz
229244
aws s3 cp $< s3://bbop-sqlite/$*.db.gz --acl public-read
230245

246+
247+
# Test documentation locally
248+
serve: mkd-serve
249+
250+
# Python datamodel
251+
$(PYMODEL):
252+
mkdir -p $@
253+
254+
255+
$(DOCDIR):
256+
mkdir -p $@
257+
258+
testdoc: gendoc serve
259+
260+
MKDOCS = $(RUN) mkdocs
261+
mkd-%:
262+
$(MKDOCS) $*
263+
231264
################################################
232265
#### Commands for building the Docker image ####
233266
################################################

‎config.env‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
LINKML_GENERATORS_PROJECT_ARGS=--config-file config.yaml
2+
3+
### Extra layer of configuration for Makefile beyond
4+
### what 'gen-project --config-file config.yaml' provides.
5+
### Uncomment and set environment variables as needed.
6+
7+
# LINKML_GENERATORS_MARKDOWN_ARGS=--no-mergeimports
8+

‎docgen-templates/class.md.jinja2‎

Lines changed: 71 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,57 +1,59 @@
1-
# Class: {{ gen.name(element) }}
1+
{%- if element.title %}
2+
{%- set title = element.title ~ ' (' ~ element.name ~ ')' -%}
3+
{%- else %}
4+
{%- if gen.use_class_uris -%}
5+
{%- set title = element.name -%}
6+
{%- else -%}
7+
{%- set title = gen.name(element) -%}
8+
{%- endif -%}
9+
{%- endif -%}
10+
11+
{% macro compute_range(slot) -%}
12+
{%- if slot.any_of or slot.exactly_one_of -%}
13+
{%- for subslot_range in schemaview.slot_range_as_union(slot) -%}
14+
{{ gen.link(subslot_range) }}
15+
{%- if not loop.last -%}
16+
&nbsp;or&nbsp;<br />
17+
{%- endif -%}
18+
{%- endfor -%}
19+
{%- else -%}
20+
{{ gen.link(slot.range) }}
21+
{%- endif -%}
22+
{% endmacro %}
23+
24+
# Class: {{ title }}
225

326
{%- if header -%}
427
{{header}}
528
{%- endif -%}
629

730

831
{% if element.description %}
9-
_{{ element.description }}_
32+
{% set element_description_lines = element.description.split('\n') %}
33+
{% for element_description_line in element_description_lines %}
34+
_{{ element_description_line }}_
35+
{% endfor %}
1036
{% endif %}
1137

1238
{% if element.abstract %}
1339
* __NOTE__: this is an abstract class and should not be instantiated directly
1440
{% endif %}
15-
{% if element.mixin %}
16-
* __NOTE__: this is a mixin class intended to be used in combination with other classes, and not used directly
17-
{% endif %}
1841

1942
URI: {{ gen.uri_link(element) }}
2043

2144

22-
23-
{% if schemaview.class_parents(element.name) %}
45+
{% if diagram_type == "er_diagram" %}
2446
```{{ gen.mermaid_directive() }}
25-
classDiagram
26-
{% for s in schemaview.class_parents(element.name)|sort(attribute='name') -%}
27-
{{ gen.name(schemaview.get_element(s)) }} <|-- {{ gen.name(element) }}
28-
{% endfor %}
29-
{% for s in schemaview.class_induced_slots(element.name)|sort(attribute='name') -%}
30-
{{ gen.name(element) }} : {{gen.name(s)}}
31-
{% endfor %}
32-
47+
{{ gen.mermaid_diagram([element.name]) }}
3348
```
34-
{% elif schemaview.class_children(element.name) %}
35-
```{{ gen.mermaid_directive() }}
36-
classDiagram
37-
{% for s in schemaview.class_children(element.name)|sort(attribute='name') -%}
38-
{{ gen.name(element) }} <|-- {{ gen.name(schemaview.get_element(s)) }}
39-
{% endfor %}
40-
{% for s in schemaview.class_induced_slots(element.name)|sort(attribute='name') -%}
41-
{{ gen.name(element) }} : {{gen.name(s)}}
42-
{% endfor %}
49+
{% elif diagram_type == "plantuml_class_diagram" %}
50+
```puml
51+
{{ gen.mermaid_diagram([element.name]) }}
4352
```
4453
{% else %}
45-
```{{ gen.mermaid_directive() }}
46-
classDiagram
47-
class {{ gen.name(element) }}
48-
{% for s in schemaview.class_induced_slots(element.name)|sort(attribute='name') -%}
49-
{{ gen.name(element) }} : {{gen.name(s)}}
50-
{% endfor %}
51-
```
54+
{% include "class_diagram.md.jinja2" %}
5255
{% endif %}
5356

54-
5557
{% if schemaview.class_parents(element.name) or schemaview.class_children(element.name, mixins=False) %}
5658

5759
## Usage
@@ -68,19 +70,36 @@ SELECT * FROM {{element.name}};
6870

6971
## Slots
7072

71-
| Name | Cardinality and Range | Description |
72-
| --- | --- | --- |
73-
{% for s in schemaview.class_induced_slots(element.name) -%}
74-
| {{gen.link(s)}} | {{ gen.cardinality(s) }} <br/> {{gen.link(s.range)}} | {{s.description|enshorten}} |
73+
| Name | Cardinality and Range | Description | Inheritance |
74+
| --- | --- | --- | --- |
75+
{% if gen.get_direct_slots(element)|length > 0 %}
76+
{%- for slot in gen.get_direct_slots(element) -%}
77+
| {{ gen.link(slot) }} | {{ gen.cardinality(slot) }} <br/> {{ compute_range(slot) }} | {{ slot.description|enshorten }} | direct |
78+
{% endfor -%}
79+
{% endif -%}
80+
{% if gen.get_indirect_slots(element)|length > 0 %}
81+
{%- for slot in gen.get_indirect_slots(element) -%}
82+
| {{ 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(', ') }} |
83+
{% endfor -%}
84+
{% endif %}
85+
86+
{% if schemaview.is_mixin(element.name) %}
87+
## Mixin Usage
88+
89+
| mixed into | description |
90+
| --- | --- |
91+
{% for c in schemaview.class_children(element.name, is_a=False) -%}
92+
| {{ gen.link(c) }} | {{ schemaview.get_class(c).description|enshorten }} |
7593
{% endfor %}
94+
{% endif %}
7695

96+
{% if schemaview.usage_index().get(element.name) %}
7797
## Usages
7898

79-
{% if schemaview.usage_index().get(element.name) %}
8099
| used by | used in | type | used |
81100
| --- | --- | --- | --- |
82101
{% for usage in schemaview.usage_index().get(element.name) -%}
83-
| {{gen.link(usage.used_by)}} | {{gen.link(usage.slot)}} | {{usage.metaslot}} | {{usage.used }} |
102+
| {{gen.link(usage.used_by)}} | {{gen.link(usage.slot)}} | {{usage.metaslot}} | {{ gen.link(usage.used) }} |
84103
{% endfor %}
85104
{% endif %}
86105

@@ -128,14 +147,25 @@ This class has a SQL view definition:
128147
| --- | --- |
129148
{% for m, mt in schemaview.get_mappings(element.name).items() -%}
130149
{% if mt|length > 0 -%}
131-
| {{ m }} | {{ mt }} |
150+
| {{ m }} | {{ mt|join(', ') }} |
132151
{% endif -%}
133152
{% endfor %}
134153

135154
{% endif -%}
136155

156+
{% if gen.example_object_blobs(element.name) -%}
157+
## Examples
158+
{% for name, blob in gen.example_object_blobs(element.name) -%}
159+
### Example: {{name}}
160+
161+
```yaml
162+
{{ blob }}
163+
```
164+
{% endfor %}
165+
{% endif %}
166+
137167

138-
## LinkML Specification
168+
## LinkML Source
139169

140170
<!-- TODO: investigate https://stackoverflow.com/questions/37606292/how-to-create-tabbed-code-blocks-in-mkdocs-or-sphinx -->
141171

@@ -157,4 +187,4 @@ This class has a SQL view definition:
157187

158188
{%- if footer -%}
159189
{{footer}}
160-
{%- endif -%}
190+
{%- endif -%}

‎docgen-templates/common_metadata.md.jinja2‎

Lines changed: 30 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,22 @@
1+
{% if element.aliases %}
2+
## Aliases
3+
4+
{% for alias in element.aliases %}
5+
* {{ alias }}
6+
{%- endfor %}
7+
{% endif %}
8+
9+
10+
{% if element.examples %}
11+
## Examples
12+
13+
| Value |
14+
| --- |
15+
{% for x in element.examples -%}
16+
| {{ x.value }} |
17+
{% endfor %}
18+
{% endif -%}
19+
120
{% if element.comments -%}
221
## Comments
322

@@ -14,6 +33,14 @@
1433
{% endfor %}
1534
{% endif -%}
1635

36+
{% if element.see_also -%}
37+
## See Also
38+
39+
{% for x in element.see_also -%}
40+
* {{ gen.uri_link(x) }}
41+
{% endfor %}
42+
{% endif -%}
43+
1744
## Identifier and Mapping Information
1845

1946
{% if element.id_prefixes %}
@@ -33,7 +60,9 @@ Instances of this class *should* have identifiers with one of the following pref
3360
| property | value |
3461
| --- | --- |
3562
{% for a in element.annotations -%}
36-
| {{a}} | {{ element.annotations[a].value }} |
63+
{%- if a|string|first != '_' -%}
64+
| {{ a }} | {{ element.annotations[a].value }} |
65+
{%- endif -%}
3766
{% endfor %}
3867
{% endif %}
3968

‎docgen-templates/enum.md.jinja2‎

Lines changed: 23 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,40 @@
1-
# {{ gen.name(element) }}
1+
# Enum: {{ gen.name(element) }}
22

3-
{{ element.description }}
3+
{% if element.description %}
4+
{% set element_description_lines = element.description.split('\n') %}
5+
{% for element_description_line in element_description_lines %}
6+
_{{ element_description_line }}_
7+
{% endfor %}
8+
{% endif %}
49

5-
URI: {{ gen.uri(element) }}
10+
URI: {{ gen.link(element) }}
611

712
{% if element.permissible_values -%}
813
## Permissible Values
914

10-
| Value | Meaning | Description | Info |
11-
| --- | --- | --- | --- |
15+
| Value | Meaning | Description |
16+
| --- | --- | --- |
1217
{% for pv in element.permissible_values.values() -%}
13-
| {{pv.text}} | {{pv.meaning}} | {{pv.description|enshorten}} | |
18+
| {{pv.text}} | {{pv.meaning}} | {{pv.description|enshorten}} |
1419
{% endfor %}
1520
{% else %}
1621
_This is a dynamic enum_
1722
{% endif %}
1823

24+
{% set slots_for_enum = schemaview.get_slots_by_enum(element.name) %}
25+
{% if slots_for_enum is defined and slots_for_enum|length > 0 -%}
26+
## Slots
27+
28+
| Name | Description |
29+
| --- | --- |
30+
{% for s in schemaview.get_slots_by_enum(element.name) -%}
31+
| {{gen.link(s)}} | {{s.description|enshorten}} |
32+
{% endfor %}
33+
{% endif %}
34+
1935
{% include "common_metadata.md.jinja2" %}
2036

21-
## Schema
37+
## LinkML Source
2238

2339
<details>
2440
```yaml

‎docgen-templates/index.md.jinja2‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,35 @@
11
# {% if schema.title %}{{ schema.title }}{% else %}{{ schema.name }}{% endif %}
22

3-
{{ schema.description }}
3+
{% if schema.description %}{{ schema.description }}{% endif %}
44

55
URI: {{ schema.id }}
6+
67
Name: {{ schema.name }}
78

9+
{% if include_top_level_diagram %}
10+
11+
## Schema Diagram
12+
13+
```{{ gen.mermaid_directive() }}
14+
{{ gen.mermaid_diagram() }}
15+
```
16+
{% endif %}
17+
818
## Classes
919

1020
| Class | Description |
1121
| --- | --- |
22+
{% if gen.hierarchical_class_view -%}
23+
{% for u, v in gen.class_hierarchy_as_tuples() -%}
24+
{%- set link = gen.link(schemaview.get_class(v)) -%}
25+
{%- set hi = "**" if schemaview.get_class(v, imports=False) else "*" -%}
26+
| {{ "&nbsp;"|safe*u*8 }}{{ hi }}{{ link }}{{ hi }} | {{ schemaview.get_class(v).description }} |
27+
{% endfor %}
28+
{% else -%}
1229
{% for c in gen.all_class_objects()|sort(attribute=sort_by) -%}
1330
| {{gen.link(c)}} | {{c.description|enshorten}} |
1431
{% endfor %}
32+
{% endif %}
1533

1634
## Slots
1735

0 commit comments

Comments
 (0)