From 5408df29610f7c61e570d62c334f0bc41d817c93 Mon Sep 17 00:00:00 2001 From: John Bartholomew Date: Tue, 18 Feb 2025 21:06:45 +0000 Subject: [PATCH 1/3] chore: jsonnetfmt the jsonnet source files in doc/ directory --- doc/_stdlib_gen/stdlib.jsonnet | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/_stdlib_gen/stdlib.jsonnet b/doc/_stdlib_gen/stdlib.jsonnet index 00841cf87..33d3da129 100644 --- a/doc/_stdlib_gen/stdlib.jsonnet +++ b/doc/_stdlib_gen/stdlib.jsonnet @@ -73,7 +73,7 @@ local group(group_spec, prefix) = ]; local stdlibPage = [ - in_panel(html.h1({id: 'standard_library'}, 'Standard Library')), + in_panel(html.h1({ id: 'standard_library' }, 'Standard Library')), '', in_panel(content.intro), '', From 02cb454879ef0c558e0427b23eae89d2d7e10378 Mon Sep 17 00:00:00 2001 From: John Bartholomew Date: Tue, 18 Feb 2025 21:09:01 +0000 Subject: [PATCH 2/3] chore: update generated stdlib reference html --- doc/ref/stdlib.html | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/ref/stdlib.html b/doc/ref/stdlib.html index 79703bbbb..5236bc4a3 100644 --- a/doc/ref/stdlib.html +++ b/doc/ref/stdlib.html @@ -250,12 +250,16 @@

    std.atan2(y, x)
    std.deg2rad(x)
    std.rad2deg(x)
+
    std.hypot(a, b)
    std.round(x)
    std.isEven(x)
    std.isOdd(x)
    std.isInteger(x)
    std.isDecimal(x)
+

+ The constant std.pi is also available. +

The function std.mod(a, b) is what the % operator is desugared to. It performs modulo arithmetic if the left hand side is a number, or if the left hand side is a string, From 8f48de6a4802f3f861df505027e867eed7fbf02e Mon Sep 17 00:00:00 2001 From: John Bartholomew Date: Tue, 18 Feb 2025 21:10:14 +0000 Subject: [PATCH 3/3] docs: fix formatting of examples for std.manifest* functions fixes #1205 --- doc/_stdlib_gen/stdlib-content.jsonnet | 31 +++-- doc/_stdlib_gen/stdlib.jsonnet | 5 +- doc/ref/stdlib.html | 160 ++++++++++++++++++------- 3 files changed, 138 insertions(+), 58 deletions(-) diff --git a/doc/_stdlib_gen/stdlib-content.jsonnet b/doc/_stdlib_gen/stdlib-content.jsonnet index 27b1d63e2..c2090e7a9 100644 --- a/doc/_stdlib_gen/stdlib-content.jsonnet +++ b/doc/_stdlib_gen/stdlib-content.jsonnet @@ -1,5 +1,14 @@ local html = import 'html.libsonnet'; +local exampleDocMultiline(mid, ex) = + html.spaceless([ + html.p({}, 'Example:'), + html.pre({}, ex.input), + html.p({}, mid), + html.pre({}, ex.output), + ]) +; + { intro: html.paragraphs([ ||| @@ -772,7 +781,7 @@ local html = import 'html.libsonnet'; |||), ], examples: [ - { + exampleDocMultiline('Yields a string containing this JSON:', { input: ||| std.manifestJsonEx( { @@ -796,8 +805,8 @@ local html = import 'html.libsonnet'; y: { a: 1, b: 2, c: [1, 2] }, }, ' ' ), - }, - { + }), + exampleDocMultiline('Yields a string containing this JSON:', { input: ||| std.manifestJsonEx( { @@ -812,7 +821,7 @@ local html = import 'html.libsonnet'; y: { a: 1, b: [1, 2] }, }, '', ' ', ' : ' ), - }, + }), ], }, { @@ -824,7 +833,7 @@ local html = import 'html.libsonnet'; it calls std.manifestJsonEx with a 4-space indent: |||, examples: [ - { + exampleDocMultiline('Yields a string containing this JSON:', { input: ||| std.manifestJson( { @@ -848,7 +857,7 @@ local html = import 'html.libsonnet'; y: { a: 1, b: 2, c: [1, 2] }, } ), - }, + }), ], }, { @@ -860,7 +869,7 @@ local html = import 'html.libsonnet'; it calls std.manifestJsonEx: |||, examples: [ - { + exampleDocMultiline('Yields a string containing this JSON:', { input: ||| std.manifestJsonMinified( { @@ -884,7 +893,7 @@ local html = import 'html.libsonnet'; y: { a: 1, b: 2, c: [1, 2] }, } ), - }, + }), ], }, { @@ -1055,7 +1064,7 @@ local html = import 'html.libsonnet'; one or more whitespaces that are used for indentation: |||, examples: [ - { + exampleDocMultiline('Yields a string containing this TOML file:', { input: ||| std.manifestTomlEx({ key1: "value", @@ -1094,7 +1103,7 @@ local html = import 'html.libsonnet'; ], }, ' ') ), - }, + }), ], }, ], @@ -1602,7 +1611,7 @@ local html = import 'html.libsonnet'; params: ['o'], availableSince: '0.20.0', description: ||| - Returns an array of objects from the given object, each object having two fields: + Returns an array of objects from the given object, each object having two fields: key (string) and value (object). Does not include hidden fields. |||, }, diff --git a/doc/_stdlib_gen/stdlib.jsonnet b/doc/_stdlib_gen/stdlib.jsonnet index 33d3da129..c2a7b8ede 100644 --- a/doc/_stdlib_gen/stdlib.jsonnet +++ b/doc/_stdlib_gen/stdlib.jsonnet @@ -15,7 +15,10 @@ local exampleDoc(ex) = else html.spaceless([html.code({}, ex.input), ' yields ', html.code({}, manifestJsonSingleLine(ex.output))]) ; - html.p({}, html.spaceless(['Example: ', exRep, '.'])) + if std.objectHas(ex, 'type') then + ex + else + html.p({}, html.spaceless(['Example: ', exRep, '.'])) ; local hgroup(body) = html.div({ class: 'hgroup' }, body); diff --git a/doc/ref/stdlib.html b/doc/ref/stdlib.html index 5236bc4a3..dae270f3c 100644 --- a/doc/ref/stdlib.html +++ b/doc/ref/stdlib.html @@ -1549,20 +1549,42 @@

of an object field:

- Example: std.manifestJsonEx( - { - x: [1, 2, 3, true, false, null, - "string\nstring"], - y: { a: 1, b: 2, c: [1, 2] }, - }, " ") yields "{\n \"x\": [\n 1,\n 2,\n 3,\n true,\n false,\n null,\n \"string\\nstring\"\n ],\n \"y\": {\n \"a\": 1,\n \"b\": 2,\n \"c\": [\n 1,\n 2\n ]\n }\n}". -

+ Example: + 

std.manifestJsonEx(
+{
+    x: [1, 2, 3, true, false, null,
+        "string\nstring"],
+    y: { a: 1, b: 2, c: [1, 2] },
+}, "    ")

+ Yields a string containing this JSON: + 

{
+    "x": [
+        1,
+        2,
+        3,
+        true,
+        false,
+        null,
+        "string\nstring"
+    ],
+    "y": {
+        "a": 1,
+        "b": 2,
+        "c": [
+            1,
+            2
+        ]
+    }
+}

- Example: std.manifestJsonEx( - { - x: [1, 2, "string\nstring"], - y: { a: 1, b: [1, 2] }, - }, "", " ", " : ") yields "{ \"x\" : [ 1, 2, \"string\\nstring\" ], \"y\" : { \"a\" : 1, \"b\" : [ 1, 2 ] } }". -

+ Example: + 

std.manifestJsonEx(
+{
+  x: [1, 2, "string\nstring"],
+  y: { a: 1, b: [1, 2] },
+}, "", " ", " : ")

+ Yields a string containing this JSON: + 

{ "x" : [ 1, 2, "string\nstring" ], "y" : { "a" : 1, "b" : [ 1, 2 ] } }
@@ -1591,13 +1613,33 @@

it calls std.manifestJsonEx with a 4-space indent:

- Example: std.manifestJson( - { - x: [1, 2, 3, true, false, null, - "string\nstring"], - y: { a: 1, b: 2, c: [1, 2] }, - }) yields "{\n \"x\": [\n 1,\n 2,\n 3,\n true,\n false,\n null,\n \"string\\nstring\"\n ],\n \"y\": {\n \"a\": 1,\n \"b\": 2,\n \"c\": [\n 1,\n 2\n ]\n }\n}". -

+ Example: + 

std.manifestJson(
+{
+    x: [1, 2, 3, true, false, null,
+        "string\nstring"],
+    y: { a: 1, b: 2, c: [1, 2] },
+})

+ Yields a string containing this JSON: + 

{
+    "x": [
+        1,
+        2,
+        3,
+        true,
+        false,
+        null,
+        "string\nstring"
+    ],
+    "y": {
+        "a": 1,
+        "b": 2,
+        "c": [
+            1,
+            2
+        ]
+    }
+}
@@ -1626,13 +1668,15 @@

it calls std.manifestJsonEx:

- Example: std.manifestJsonMinified( - { - x: [1, 2, 3, true, false, null, - "string\nstring"], - y: { a: 1, b: 2, c: [1, 2] }, - }) yields "{\"x\":[1,2,3,true,false,null,\"string\\nstring\"],\"y\":{\"a\":1,\"b\":2,\"c\":[1,2]}}". -

+ Example: + 

std.manifestJsonMinified(
+{
+    x: [1, 2, 3, true, false, null,
+        "string\nstring"],
+    y: { a: 1, b: 2, c: [1, 2] },
+})

+ Yields a string containing this JSON: + 

{"x":[1,2,3,true,false,null,"string\nstring"],"y":{"a":1,"b":2,"c":[1,2]}}
@@ -1844,24 +1888,48 @@

one or more whitespaces that are used for indentation:

- Example: std.manifestTomlEx({ - key1: "value", - key2: 1, - section: { - a: 1, - b: "str", - c: false, - d: [1, "s", [2, 3]], - subsection: { - k: "v", - }, - }, - sectionArray: [ - { k: "v1", v: 123 }, - { k: "v2", c: "value2" }, - ], - }, " ") yields "key1 = \"value\"\nkey2 = 1\n\n[section]\n a = 1\n b = \"str\"\n c = false\n d = [\n 1,\n \"s\",\n [ 2, 3 ]\n ]\n\n [section.subsection]\n k = \"v\"\n\n[[sectionArray]]\n k = \"v1\"\n v = 123\n\n[[sectionArray]]\n c = \"value2\"\n k = \"v2\"". -

+ Example: + 

std.manifestTomlEx({
+  key1: "value",
+  key2: 1,
+  section: {
+    a: 1,
+    b: "str",
+    c: false,
+    d: [1, "s", [2, 3]],
+    subsection: {
+      k: "v",
+    },
+  },
+  sectionArray: [
+    { k: "v1", v: 123 },
+    { k: "v2", c: "value2" },
+  ],
+}, "  ")

+ Yields a string containing this TOML file: + 

key1 = "value"
+key2 = 1
+
+[section]
+  a = 1
+  b = "str"
+  c = false
+  d = [
+    1,
+    "s",
+    [ 2, 3 ]
+  ]
+
+  [section.subsection]
+    k = "v"
+
+[[sectionArray]]
+  k = "v1"
+  v = 123
+
+[[sectionArray]]
+  c = "value2"
+  k = "v2"
@@ -3083,7 +3151,7 @@

- Returns an array of objects from the given object, each object having two fields: + Returns an array of objects from the given object, each object having two fields: key (string) and value (object). Does not include hidden fields.