From 6a624d0016adfc49b58798c01bc856ff8a6a8deb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Sat, 12 Oct 2024 18:00:45 +0200 Subject: [PATCH 1/3] Enforce consistent vertical spacing between paragraphs in endpoint definitions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Use `p` elements to separate paragraphs instead of `br` and enforce single paragraphs to be wrapped in `p` for consistency. Signed-off-by: Kévin Commaille --- assets/scss/_styles_project.scss | 5 +++++ layouts/partials/added-in.html | 14 +++++++------- layouts/partials/changed-in.html | 5 +++-- .../partials/openapi/render-content-type.html | 7 ++++++- .../partials/openapi/render-object-table.html | 18 +++++++++++++++--- 5 files changed, 36 insertions(+), 13 deletions(-) diff --git a/assets/scss/_styles_project.scss b/assets/scss/_styles_project.scss index 639536974..f28a1267d 100644 --- a/assets/scss/_styles_project.scss +++ b/assets/scss/_styles_project.scss @@ -410,6 +410,11 @@ footer { border-top: 1px $table-border-color solid; } + td > p:last-child { + // Avoid unnecessary space at the bottom of the cells. + margin-bottom: 0; + } + &.object-table, &.response-table, &.content-type-table { border: 1px $table-border-color solid; diff --git a/layouts/partials/added-in.html b/layouts/partials/added-in.html index c75c0676d..1ab3ad4cb 100644 --- a/layouts/partials/added-in.html +++ b/layouts/partials/added-in.html @@ -1,13 +1,13 @@ -{{ $ver := .v }} -{{ $this := .this }} +{{ $ver := .v -}} +{{ $this := .this -}} {{/* This differs from the shortcode added-in by wanting to be a block instead of inline and by slightly altering the rendered text as a result. */}} -{{ if $this }} - **New in this version.** -{{ else }} - **Added in `v{{ $ver }}`** -{{ end }} +{{ if $this -}} +

New in this version.

+{{ else -}} +

Added in v{{ $ver }}

+{{ end -}} diff --git a/layouts/partials/changed-in.html b/layouts/partials/changed-in.html index 8a815904c..61aba5b1e 100644 --- a/layouts/partials/changed-in.html +++ b/layouts/partials/changed-in.html @@ -6,9 +6,10 @@ version -> details pairs. */ -}} {{ range $ver, $details := .changes_dict -}} -

+

Changed in v{{ $ver }}: {{ $details | markdownify }} -{{ end }} +

+{{ end -}} diff --git a/layouts/partials/openapi/render-content-type.html b/layouts/partials/openapi/render-content-type.html index a7c90e1ac..b1f8239d6 100644 --- a/layouts/partials/openapi/render-content-type.html +++ b/layouts/partials/openapi/render-content-type.html @@ -21,7 +21,12 @@ {{ $mime }} - {{ $body.schema.description | markdownify -}} + {{/* + Force the rendering as a block so the description is always inside a + paragraph. This allows to always keep the same spacing between paragraphs + when adding added-in and changed-in paragraphs. + */}} + {{ $body.schema.description | page.RenderString (dict "display" "block") -}} {{ if (index $body.schema "x-addedInMatrixVersion") }}{{ partial "added-in" (dict "v" (index $body.schema "x-addedInMatrixVersion")) }}{{ end -}} {{ if (index $body.schema "x-changedInMatrixVersion") }}{{ partial "changed-in" (dict "changes_dict" (index $body.schema "x-changedInMatrixVersion")) }}{{ end -}} diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html index 656f556a7..59c98c33c 100644 --- a/layouts/partials/openapi/render-object-table.html +++ b/layouts/partials/openapi/render-object-table.html @@ -306,9 +306,21 @@ * `x-changedInMatrixVersion`: optional string indicating in which Matrix spec version this property was last changed. */}} -{{ define "partials/property-description" }} - {{ if .required }}Required: {{end -}} - {{ .property.description | markdownify -}} +{{ define "partials/property-description" -}} + {{ $description := .property.description -}} + {{ if .required -}} + {{/* + Concatenate "Required:" to make it part of the first paragraph of the + description. + */}} + {{- $description = printf "Required: %s" $description -}} + {{ end -}} + {{/* + Force the rendering as a block so the description is always inside a + paragraph. This allows to always keep the same spacing between paragraphs + when adding added-in and changed-in paragraphs. + */}} + {{ $description | page.RenderString (dict "display" "block") -}} {{ if .property.enum }}

One of: [{{ delimit .property.enum ", " }}].

{{ end -}} {{ if (index .property "x-addedInMatrixVersion") }}{{ partial "added-in" (dict "v" (index .property "x-addedInMatrixVersion")) }}{{ end -}} {{ if (index .property "x-changedInMatrixVersion") }}{{ partial "changed-in" (dict "changes_dict" (index .property "x-changedInMatrixVersion")) }}{{ end -}} From fbcdfd7d2e974391021181f53eac5f42e9087f59 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Sat, 12 Oct 2024 18:11:02 +0200 Subject: [PATCH 2/3] Add changelog MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- changelogs/internal/newsfragments/1969.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/internal/newsfragments/1969.clarification diff --git a/changelogs/internal/newsfragments/1969.clarification b/changelogs/internal/newsfragments/1969.clarification new file mode 100644 index 000000000..db9e1a1af --- /dev/null +++ b/changelogs/internal/newsfragments/1969.clarification @@ -0,0 +1 @@ +Enforce consistent vertical spacing between paragraphs in endpoint definitions. \ No newline at end of file From e95360b06e19da336b996d37ad6833fe33e4163b Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Tue, 29 Oct 2024 15:20:49 +0000 Subject: [PATCH 3/3] Update layouts/partials/openapi/render-object-table.html --- layouts/partials/openapi/render-object-table.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html index 59c98c33c..7343a839c 100644 --- a/layouts/partials/openapi/render-object-table.html +++ b/layouts/partials/openapi/render-object-table.html @@ -310,7 +310,7 @@ {{ $description := .property.description -}} {{ if .required -}} {{/* - Concatenate "Required:" to make it part of the first paragraph of the + Prepend "Required:" to make it part of the first paragraph of the description. */}} {{- $description = printf "Required: %s" $description -}}