From c2578db12ebd6e0582d8c76c2630346a2edd44a6 Mon Sep 17 00:00:00 2001 From: Alasdair Gray Date: Thu, 26 Oct 2023 10:44:04 +0100 Subject: [PATCH 1/6] Add name to container when it runs --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 47c5639..c00625f 100644 --- a/Makefile +++ b/Makefile @@ -179,7 +179,7 @@ mkd-%: gendoc # Needed as macOS does not support multiple entities with the same name but different cases docker-serve: docker build -t model-docs . - docker run -p 8080:8080 model-docs + docker run --name ukgov-metadata-docs -p 8080:8080 model-docs ########################################################### # CLEANUP ########################################################### From e71431c00010b9f123670391c89f569afaf56fe6 Mon Sep 17 00:00:00 2001 From: Alasdair Gray Date: Thu, 26 Oct 2023 10:44:38 +0100 Subject: [PATCH 2/6] Present property attributes in a table #51 Update property definitions so predominant cardinalities are presented in the property page --- src/docs/templates/slot.md.jinja2 | 28 ++++--------------- ...ss_government_metadata_exchange_model.yaml | 28 ++++++++++++------- 2 files changed, 23 insertions(+), 33 deletions(-) diff --git a/src/docs/templates/slot.md.jinja2 b/src/docs/templates/slot.md.jinja2 index c7a0985..b3515f2 100644 --- a/src/docs/templates/slot.md.jinja2 +++ b/src/docs/templates/slot.md.jinja2 @@ -15,31 +15,13 @@ {% endfor %} {% endif %} -URI: {{ gen.uri_link(element) }} +## Obligation and Cardinality -Range: {{gen.link(element.range)}} +The obligation or cardinality can be overridden when used by classes. Check the [Applicable Classes](#applicable-classes) section below for details. -{% if element.multivalued %} -Multivalued: {{ element.multivalued }} -{% endif -%} - -{% if element.required %} -Required: {{ element.required }} -{% elif element.recommended %} -Recommended: {{ element.recommended }} -{% endif -%} - -{% if element.minimum_value is not none %} -Minimum Value: {{ element.minimum_value|int }} -{% endif -%} - -{% if element.maximum_value is not none %} -Maximum Value: {{ element.maximum_value|int }} -{% endif -%} - -{% if element.pattern %} -Regex pattern: {{ '`' }}{{ element.pattern }}{{ '`' }} -{% endif -%} +| URL | Range | Obligation | Cardinality | +|-----------------------------|-----------------------------|-------------|-------------| +| {{ gen.uri_link(element) }} | {{gen.link(element.range)}} {% if element.minimum_value is not none %}
Minimum Value: {{ element.minimum_value|int }}{% endif %}{% if element.maximum_value is not none %}
Maximum Value: {{ element.maximum_value|int }}{% endif %}{% if element.pattern %}
Regex pattern: {{ '`' }}{{ element.pattern }}{{ '`' }}{% endif %} | {% if element.required %}Mandatory{% elif element.recommended %}Recommended{% else %}Optional{% endif %} | {% if element.multivalued %}Many{% else %}One{% endif %} | {% if schemaview.is_mixin(element.name) %} Mixin: {{ element.mixin }} diff --git a/src/model/uk_cross_government_metadata_exchange_model.yaml b/src/model/uk_cross_government_metadata_exchange_model.yaml index 5fa4857..5325b96 100644 --- a/src/model/uk_cross_government_metadata_exchange_model.yaml +++ b/src/model/uk_cross_government_metadata_exchange_model.yaml @@ -72,13 +72,6 @@ classes: - type - theme - version - slot_usage: - accessRights: - required: true - description: - required: true - modified: - required: true DataService: is_a: DataResource @@ -119,6 +112,10 @@ classes: - title - type slot_usage: + accessRights: + required: false + description: + required: false modified: recommended: true @@ -145,6 +142,7 @@ slots: accessRights: slot_uri: dct:accessRights description: A rights statement that concerns how the distribution is accessed. + required: true range: AccessRightsValues address: slot_uri: vcard:hasAddress @@ -291,6 +289,7 @@ slots: description: | A concise narrative of the content of an information resource. A free-text account of the distribution. + required: true range: string comments: | purpose: @@ -450,6 +449,7 @@ Note that there could be a security risk in sharing the endpoint URL for interna modified: slot_uri: dct:modified description: The date, or date and time, on which the content of an information resource is changed. + required: true range: date comments: | purpose: @@ -563,11 +563,19 @@ Note that there could be a security risk in sharing the endpoint URL for interna summary: slot_uri: rdfs:comment description: | - "A short textual summary of the resource with a maximum length of 250 characters. - - Usage note: The intended use of this text is in a page containing multiple search results. If omitted, the first part of the description text will be used. This may be up to a certain character count or the detection of a paragraph break." + A short textual summary of the resource with a maximum length of 250 characters. recommended: true range: string + pattern: ^.{1,250}$ + comments: | + purpose: + The intended use of this text is in a page containing multiple search results where a short one sentence or so summary is needed. + + If omitted, the first part of the description text will be used. This may be up to a certain character count or the detection of a paragraph break, it is up to the application to decide. + distinctFrom: + - [`description`](/ukgov-metadata-exchange-model/description): to capture a full overview of the data asset + guidance: + The `summary` will be used where a short text overview of the data asset is required, e.g. in a page of search results. It should provide an idea of what the data asset provides but not give full details. Conciseness is key. telephone: slot_uri: vcard:hasTelephone description: Telephone number for the contact team From 611d84d587db980c80b89a15b8d59d4e4eb1a9ff Mon Sep 17 00:00:00 2001 From: Alasdair Gray Date: Fri, 27 Oct 2023 09:23:58 +0100 Subject: [PATCH 3/6] Improve display of Class properties --- src/docs/templates/class.md.jinja2 | 36 ++++++++++++++++++++---------- 1 file changed, 24 insertions(+), 12 deletions(-) diff --git a/src/docs/templates/class.md.jinja2 b/src/docs/templates/class.md.jinja2 index 0d8c1d4..6616c3e 100644 --- a/src/docs/templates/class.md.jinja2 +++ b/src/docs/templates/class.md.jinja2 @@ -40,19 +40,31 @@ URI: {{ gen.uri_link(element) }} {% endif %} ## Properties - -| Name | Cardinality and Range | Description | Inheritance | +{% macro slot_table_header() -%} +| Name | Range | Description | Cardinality | | --- | --- | --- | --- | -{% if gen.get_direct_slots(element)|length > 0 %} -{%- for slot in gen.get_direct_slots(element) -%} -| {{ gen.link(slot) }} | {{ gen.cardinality(slot) }}
{{ 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) }}
{{ gen.link(slot.range) }} | {{ slot.description|enshorten }} | {{ gen.links(gen.get_slot_inherited_from(element.name, slot.name))|join(', ') }} | -{% endfor -%} -{% endif %} +{%- endmacro %} + +{% macro slot_table(slot) -%} +| {{gen.link(slot)}} | {{ gen.link(slot.range) }}{% if slot.minimum_value is not none %}
Minimum Value: {{ slot.minimum_value|int }}{% endif %}{% if slot.maximum_value is not none %}
Maximum Value: {{ slot.maximum_value|int }}{% endif %}{% if slot.pattern %}
Regex pattern: {{ '`' }}{{ slot.pattern }}{{ '`' }}{% endif %} | {{ slot.description|enshorten }} | {% if slot.multivalued %}Many{% else %}One{% endif %} | +{%- endmacro %} + +### Mandatory Properties +{{ slot_table_header() }} +{% for slot in schemaview.class_induced_slots(element.name) | rejectattr("required", "none") | sort(attribute='name') -%} +{{ slot_table(slot) }} +{% endfor %} + +### Recommended Properties +{{ slot_table_header() }} +{% for slot in schemaview.class_induced_slots(element.name) | rejectattr("recommended", "none") | sort(attribute='name') -%} +{{ slot_table(slot) }} +{% endfor %} +### Optional Properties +{{ slot_table_header() }} +{% for slot in schemaview.class_induced_slots(element.name) | rejectattr("required") | rejectattr("recommended") | sort(attribute='name') -%} +{{ slot_table(slot) }} +{% endfor %} {% if schemaview.is_mixin(element.name) %} ## Mixin Usage From fda63cb21bcc6868ddcaf23aacdd194516472cf2 Mon Sep 17 00:00:00 2001 From: Alasdair Gray Date: Fri, 27 Oct 2023 09:46:32 +0100 Subject: [PATCH 4/6] Refactor and only display if there are props --- src/docs/templates/class.md.jinja2 | 32 ++++++++++++------------------ 1 file changed, 13 insertions(+), 19 deletions(-) diff --git a/src/docs/templates/class.md.jinja2 b/src/docs/templates/class.md.jinja2 index 6616c3e..4bfafc4 100644 --- a/src/docs/templates/class.md.jinja2 +++ b/src/docs/templates/class.md.jinja2 @@ -40,31 +40,25 @@ URI: {{ gen.uri_link(element) }} {% endif %} ## Properties -{% macro slot_table_header() -%} +{% macro slots_table(heading, slots) -%} +{% if slots | length > 0 %} +### {{ heading }} Properties | Name | Range | Description | Cardinality | | --- | --- | --- | --- | -{%- endmacro %} - -{% macro slot_table(slot) -%} +{% for slot in slots -%} | {{gen.link(slot)}} | {{ gen.link(slot.range) }}{% if slot.minimum_value is not none %}
Minimum Value: {{ slot.minimum_value|int }}{% endif %}{% if slot.maximum_value is not none %}
Maximum Value: {{ slot.maximum_value|int }}{% endif %}{% if slot.pattern %}
Regex pattern: {{ '`' }}{{ slot.pattern }}{{ '`' }}{% endif %} | {{ slot.description|enshorten }} | {% if slot.multivalued %}Many{% else %}One{% endif %} | +{% endfor %} +{% endif %} {%- endmacro %} -### Mandatory Properties -{{ slot_table_header() }} -{% for slot in schemaview.class_induced_slots(element.name) | rejectattr("required", "none") | sort(attribute='name') -%} -{{ slot_table(slot) }} -{% endfor %} +{% set slots = schemaview.class_induced_slots(element.name) | rejectattr("required", "none") | sort(attribute='name') -%} +{{ slots_table("Mandatory", slots) }} -### Recommended Properties -{{ slot_table_header() }} -{% for slot in schemaview.class_induced_slots(element.name) | rejectattr("recommended", "none") | sort(attribute='name') -%} -{{ slot_table(slot) }} -{% endfor %} -### Optional Properties -{{ slot_table_header() }} -{% for slot in schemaview.class_induced_slots(element.name) | rejectattr("required") | rejectattr("recommended") | sort(attribute='name') -%} -{{ slot_table(slot) }} -{% endfor %} +{% set slots = schemaview.class_induced_slots(element.name) | rejectattr("recommended", "none") | sort(attribute='name') -%} +{{ slots_table("Recommended", slots) }} + +{% set slots = schemaview.class_induced_slots(element.name) | rejectattr("required") | rejectattr("recommended") | sort(attribute='name') -%} +{{ slots_table("Optional", slots) }} {% if schemaview.is_mixin(element.name) %} ## Mixin Usage From b4f8077b26a62cf40ba23aab287c41e247ccc5de Mon Sep 17 00:00:00 2001 From: Alasdair Gray Date: Fri, 27 Oct 2023 10:20:29 +0100 Subject: [PATCH 5/6] Enforce test running when generating docs --- Makefile | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index c00625f..bc7d639 100644 --- a/Makefile +++ b/Makefile @@ -161,7 +161,8 @@ doc-setup: mkdir -p $(EXAMPLEDIR) cp src/data/*/valid/* $(EXAMPLEDIR) -gendoc: gen-examples +#gendoc: doc-setup +gendoc: test cp src/docs/*.md $(DOCDIR) cp LICENSE.md $(DOCDIR) $(RUN) gen-doc -d $(DOCDIR) \ From c724f6582800b28405aa88548569ff5b80edbade Mon Sep 17 00:00:00 2001 From: Alasdair Gray Date: Fri, 27 Oct 2023 11:24:43 +0100 Subject: [PATCH 6/6] Fix failing test where modified property is overridden --- src/docs/templates/class.md.jinja2 | 4 ++-- src/model/uk_cross_government_metadata_exchange_model.yaml | 1 + 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/src/docs/templates/class.md.jinja2 b/src/docs/templates/class.md.jinja2 index 4bfafc4..0fe4fe3 100644 --- a/src/docs/templates/class.md.jinja2 +++ b/src/docs/templates/class.md.jinja2 @@ -51,10 +51,10 @@ URI: {{ gen.uri_link(element) }} {% endif %} {%- endmacro %} -{% set slots = schemaview.class_induced_slots(element.name) | rejectattr("required", "none") | sort(attribute='name') -%} +{% set slots = schemaview.class_induced_slots(element.name) | rejectattr("required", "none") | rejectattr("required", "false") | sort(attribute='name') -%} {{ slots_table("Mandatory", slots) }} -{% set slots = schemaview.class_induced_slots(element.name) | rejectattr("recommended", "none") | sort(attribute='name') -%} +{% set slots = schemaview.class_induced_slots(element.name) | rejectattr("recommended", "none") | rejectattr("recommended", "false") | sort(attribute='name') -%} {{ slots_table("Recommended", slots) }} {% set slots = schemaview.class_induced_slots(element.name) | rejectattr("required") | rejectattr("recommended") | sort(attribute='name') -%} diff --git a/src/model/uk_cross_government_metadata_exchange_model.yaml b/src/model/uk_cross_government_metadata_exchange_model.yaml index 5594d9b..c217e76 100644 --- a/src/model/uk_cross_government_metadata_exchange_model.yaml +++ b/src/model/uk_cross_government_metadata_exchange_model.yaml @@ -117,6 +117,7 @@ classes: description: required: false modified: + required: false recommended: true Organisation: