Skip to content

Commit 88c74c8

Browse files
DuologicDuologic
committed
generating docs
1 parent 2cf81ec commit 88c74c8

File tree

12 files changed

+405
-90
lines changed

12 files changed

+405
-90
lines changed

‎_gen/lesson1.md

+20-20
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ deploy a webserver on Kubernetes.
1919

2020
Let's start with a simple `Deployment` of a webserver:
2121

22-
```jsonnet
22+
~~~jsonnet
2323
{
2424
apiVersion: 'apps/v1',
2525
kind: 'Deployment',
@@ -42,7 +42,7 @@ Let's start with a simple `Deployment` of a webserver:
4242
}
4343
4444
// example1.jsonnet
45-
```
45+
~~~
4646
<small>[Try `example1.jsonnet` in Jsonnet Playground](https://jsonnet-libs.github.io/playground/?code=ewogIGFwaVZlcnNpb246ICdhcHBzL3YxJywKICBraW5kOiAnRGVwbG95bWVudCcsCiAgbWV0YWRhdGE6IHsKICAgIG5hbWU6ICd3ZWJzZXJ2ZXInLAogIH0sCiAgc3BlYzogewogICAgcmVwbGljYXM6IDEsCiAgICB0ZW1wbGF0ZTogewogICAgICBzcGVjOiB7CiAgICAgICAgY29udGFpbmVyczogWwogICAgICAgICAgewogICAgICAgICAgICBuYW1lOiAnaHR0cGQnLAogICAgICAgICAgICBpbWFnZTogJ2h0dHBkOjIuNCcsCiAgICAgICAgICB9LAogICAgICAgIF0sCiAgICAgIH0sCiAgICB9LAogIH0sCn0K)</small>
4747

4848
A `Deployment` needs a number of configuration options, most importantly a unique `name`
@@ -57,7 +57,7 @@ with `metadata.name` and `spec.template.spec.containers[0].name`.
5757
Let's wrap this into a small `webserver` library and parameterize the name because
5858
'webserver' may be a bit too generic:
5959

60-
```jsonnet
60+
~~~jsonnet
6161
local webserver = {
6262
new(name, replicas=1): {
6363
apiVersion: 'apps/v1',
@@ -84,7 +84,7 @@ local webserver = {
8484
webserver.new('wonderful-webserver')
8585
8686
// example2.jsonnet
87-
```
87+
~~~
8888
<small>[Try `example2.jsonnet` in Jsonnet Playground](https://jsonnet-libs.github.io/playground/?code=bG9jYWwgd2Vic2VydmVyID0gewogIG5ldyhuYW1lLCByZXBsaWNhcz0xKTogewogICAgYXBpVmVyc2lvbjogJ2FwcHMvdjEnLAogICAga2luZDogJ0RlcGxveW1lbnQnLAogICAgbWV0YWRhdGE6IHsKICAgICAgbmFtZTogbmFtZSwKICAgIH0sCiAgICBzcGVjOiB7CiAgICAgIHJlcGxpY2FzOiByZXBsaWNhcywKICAgICAgdGVtcGxhdGU6IHsKICAgICAgICBzcGVjOiB7CiAgICAgICAgICBjb250YWluZXJzOiBbCiAgICAgICAgICAgIHsKICAgICAgICAgICAgICBuYW1lOiAnaHR0cGQnLAogICAgICAgICAgICAgIGltYWdlOiAnaHR0cGQ6Mi40JywKICAgICAgICAgICAgfSwKICAgICAgICAgIF0sCiAgICAgICAgfSwKICAgICAgfSwKICAgIH0sCiAgfSwKfTsKCndlYnNlcnZlci5uZXcoJ3dvbmRlcmZ1bC13ZWJzZXJ2ZXInKQo=)</small>
8989

9090
The `local` keyword makes this part of the code only available within this file, it is
@@ -99,7 +99,7 @@ respectively.
9999

100100
Let's add another function to modify the image of the httpd container:
101101

102-
```jsonnet
102+
~~~jsonnet
103103
local webserver = {
104104
new(name, replicas=1): {
105105
apiVersion: 'apps/v1',
@@ -143,7 +143,7 @@ webserver.new('wonderful-webserver')
143143
+ webserver.withImage('httpd:2.5')
144144
145145
// example3.jsonnet
146-
```
146+
~~~
147147
<small>[Try `example3.jsonnet` in Jsonnet Playground](https://jsonnet-libs.github.io/playground/?code=bG9jYWwgd2Vic2VydmVyID0gewogIG5ldyhuYW1lLCByZXBsaWNhcz0xKTogewogICAgYXBpVmVyc2lvbjogJ2FwcHMvdjEnLAogICAga2luZDogJ0RlcGxveW1lbnQnLAogICAgbWV0YWRhdGE6IHsKICAgICAgbmFtZTogbmFtZSwKICAgIH0sCiAgICBzcGVjOiB7CiAgICAgIHJlcGxpY2FzOiByZXBsaWNhcywKICAgICAgdGVtcGxhdGU6IHsKICAgICAgICBzcGVjOiB7CiAgICAgICAgICBjb250YWluZXJzOiBbCiAgICAgICAgICAgIHsKICAgICAgICAgICAgICBuYW1lOiAnaHR0cGQnLAogICAgICAgICAgICAgIGltYWdlOiAnaHR0cGQ6Mi40JywKICAgICAgICAgICAgfSwKICAgICAgICAgIF0sCiAgICAgICAgfSwKICAgICAgfSwKICAgIH0sCiAgfSwKCiAgd2l0aEltYWdlKGltYWdlKTogewogICAgbG9jYWwgY29udGFpbmVycyA9IHN1cGVyLnNwZWMudGVtcGxhdGUuc3BlYy5jb250YWluZXJzLAogICAgc3BlYys6IHsKICAgICAgdGVtcGxhdGUrOiB7CiAgICAgICAgc3BlYys6IHsKICAgICAgICAgIGNvbnRhaW5lcnM6IFsKICAgICAgICAgICAgaWYgY29udGFpbmVyLm5hbWUgPT0gJ2h0dHBkJwogICAgICAgICAgICB0aGVuIGNvbnRhaW5lciB7IGltYWdlOiBpbWFnZSB9CiAgICAgICAgICAgIGVsc2UgY29udGFpbmVyCiAgICAgICAgICAgIGZvciBjb250YWluZXIgaW4gY29udGFpbmVycwogICAgICAgICAgXSwKICAgICAgICB9LAogICAgICB9LAogICAgfSwKICB9LAp9OwoKd2Vic2VydmVyLm5ldygnd29uZGVyZnVsLXdlYnNlcnZlcicpCisgd2Vic2VydmVyLndpdGhJbWFnZSgnaHR0cGQ6Mi41JykK)</small>
148148

149149
`withImage` is an optional 'mixin' function to modify the `Deployment`, notice how the
@@ -160,7 +160,7 @@ quite verbose and hard to read.
160160

161161
Let's make the container a bit more accessible by moving it out of the `Deployment`:
162162

163-
```jsonnet
163+
~~~jsonnet
164164
local webserver = {
165165
new(name, replicas=1): {
166166
local base = self,
@@ -198,7 +198,7 @@ webserver.new('wonderful-webserver')
198198
+ webserver.withImage('httpd:2.5')
199199
200200
// example4.jsonnet
201-
```
201+
~~~
202202
<small>[Try `example4.jsonnet` in Jsonnet Playground](https://jsonnet-libs.github.io/playground/?code=bG9jYWwgd2Vic2VydmVyID0gewogIG5ldyhuYW1lLCByZXBsaWNhcz0xKTogewogICAgbG9jYWwgYmFzZSA9IHNlbGYsCgogICAgY29udGFpbmVyOjogewogICAgICBuYW1lOiAnaHR0cGQnLAogICAgICBpbWFnZTogJ2h0dHBkOjIuNCcsCiAgICB9LAoKICAgIGRlcGxveW1lbnQ6IHsKICAgICAgYXBpVmVyc2lvbjogJ2FwcHMvdjEnLAogICAgICBraW5kOiAnRGVwbG95bWVudCcsCiAgICAgIG1ldGFkYXRhOiB7CiAgICAgICAgbmFtZTogbmFtZSwKICAgICAgfSwKICAgICAgc3BlYzogewogICAgICAgIHJlcGxpY2FzOiByZXBsaWNhcywKICAgICAgICB0ZW1wbGF0ZTogewogICAgICAgICAgc3BlYzogewogICAgICAgICAgICBjb250YWluZXJzOiBbCiAgICAgICAgICAgICAgYmFzZS5jb250YWluZXIsCiAgICAgICAgICAgIF0sCiAgICAgICAgICB9LAogICAgICAgIH0sCiAgICAgIH0sCiAgICB9LAogIH0sCgogIHdpdGhJbWFnZShpbWFnZSk6IHsKICAgIGNvbnRhaW5lcis6IHsgaW1hZ2U6IGltYWdlIH0sCiAgfSwKfTsKCndlYnNlcnZlci5uZXcoJ3dvbmRlcmZ1bC13ZWJzZXJ2ZXInKQorIHdlYnNlcnZlci53aXRoSW1hZ2UoJ2h0dHBkOjIuNScpCg==)</small>
203203

204204
This makes the code a lot more succinct, no more loops and conditionals needed. The code
@@ -218,7 +218,7 @@ as `self` is late-bound any changes to `container` will be reflected in `deploym
218218
To expose the webserver, a port is configured below. Now imagine that you are not the
219219
author of this library and want to change the `ports` attribute.
220220

221-
```jsonnet
221+
~~~jsonnet
222222
local webserver = {
223223
new(name, replicas=1): {
224224
local base = self,
@@ -266,7 +266,7 @@ webserver.new('wonderful-webserver')
266266
}
267267
268268
// example6.jsonnet
269-
```
269+
~~~
270270
<small>[Try `example6.jsonnet` in Jsonnet Playground](https://jsonnet-libs.github.io/playground/?code=bG9jYWwgd2Vic2VydmVyID0gewogIG5ldyhuYW1lLCByZXBsaWNhcz0xKTogewogICAgbG9jYWwgYmFzZSA9IHNlbGYsCgogICAgY29udGFpbmVyOjogewogICAgICBuYW1lOiAnaHR0cGQnLAogICAgICBpbWFnZTogJ2h0dHBkOjIuNCcsCiAgICAgIHBvcnRzOiBbewogICAgICAgIGNvbnRhaW5lclBvcnQ6IDgwLAogICAgICB9XSwKICAgIH0sCgogICAgZGVwbG95bWVudDogewogICAgICBhcGlWZXJzaW9uOiAnYXBwcy92MScsCiAgICAgIGtpbmQ6ICdEZXBsb3ltZW50JywKICAgICAgbWV0YWRhdGE6IHsKICAgICAgICBuYW1lOiBuYW1lLAogICAgICB9LAogICAgICBzcGVjOiB7CiAgICAgICAgcmVwbGljYXM6IHJlcGxpY2FzLAogICAgICAgIHRlbXBsYXRlOiB7CiAgICAgICAgICBzcGVjOiB7CiAgICAgICAgICAgIGNvbnRhaW5lcnM6IFsKICAgICAgICAgICAgICBiYXNlLmNvbnRhaW5lciwKICAgICAgICAgICAgXSwKICAgICAgICAgIH0sCiAgICAgICAgfSwKICAgICAgfSwKICAgIH0sCiAgfSwKCiAgd2l0aEltYWdlKGltYWdlKTogewogICAgY29udGFpbmVyKzogeyBpbWFnZTogaW1hZ2UgfSwKICB9LAp9OwoKd2Vic2VydmVyLm5ldygnd29uZGVyZnVsLXdlYnNlcnZlcicpCisgd2Vic2VydmVyLndpdGhJbWFnZSgnaHR0cGQ6Mi41JykKKyB7CiAgY29udGFpbmVyKzogewogICAgcG9ydHM6IFt7CiAgICAgIGNvbnRhaW5lclBvcnQ6IDgwODAsCiAgICB9XSwKICB9LAp9Cg==)</small>
271271

272272
The author has not provided a function for that however, unlike Helm charts, it is not
@@ -288,7 +288,7 @@ library code terse and maintainable without sacrificing extensibility.
288288

289289
Avoid the 'builder' pattern:
290290

291-
```jsonnet
291+
~~~jsonnet
292292
local webserver = {
293293
new(name, replicas=1): {
294294
local base = self,
@@ -325,7 +325,7 @@ local webserver = {
325325
webserver.new('wonderful-webserver').withImage('httpd:2.5')
326326
327327
// pitfall1.jsonnet
328-
```
328+
~~~
329329
<small>[Try `pitfall1.jsonnet` in Jsonnet Playground](https://jsonnet-libs.github.io/playground/?code=bG9jYWwgd2Vic2VydmVyID0gewogIG5ldyhuYW1lLCByZXBsaWNhcz0xKTogewogICAgbG9jYWwgYmFzZSA9IHNlbGYsCgogICAgY29udGFpbmVyOjogewogICAgICBuYW1lOiAnaHR0cGQnLAogICAgICBpbWFnZTogJ2h0dHBkOjIuNCcsCiAgICB9LAoKICAgIGRlcGxveW1lbnQ6IHsKICAgICAgYXBpVmVyc2lvbjogJ2FwcHMvdjEnLAogICAgICBraW5kOiAnRGVwbG95bWVudCcsCiAgICAgIG1ldGFkYXRhOiB7CiAgICAgICAgbmFtZTogbmFtZSwKICAgICAgfSwKICAgICAgc3BlYzogewogICAgICAgIHJlcGxpY2FzOiByZXBsaWNhcywKICAgICAgICB0ZW1wbGF0ZTogewogICAgICAgICAgc3BlYzogewogICAgICAgICAgICBjb250YWluZXJzOiBbCiAgICAgICAgICAgICAgYmFzZS5jb250YWluZXIsCiAgICAgICAgICAgIF0sCiAgICAgICAgICB9LAogICAgICAgIH0sCiAgICAgIH0sCiAgICB9LAoKICAgIHdpdGhJbWFnZShpbWFnZSk6OiBzZWxmICsgewogICAgICBjb250YWluZXIrOiB7IGltYWdlOiBpbWFnZSB9LAogICAgfSwKICB9LAp9OwoKd2Vic2VydmVyLm5ldygnd29uZGVyZnVsLXdlYnNlcnZlcicpLndpdGhJbWFnZSgnaHR0cGQ6Mi41JykK)</small>
330330

331331
Notice the odd `withImage():: self + {}` structure within `new()`.
@@ -343,7 +343,7 @@ with implied meaning.
343343

344344
Applying the convention to above library would make it look like this:
345345

346-
```jsonnet
346+
~~~jsonnet
347347
local webserver = {
348348
local base = self,
349349
@@ -390,7 +390,7 @@ webserver {
390390
}
391391
392392
// pitfall2.jsonnet
393-
```
393+
~~~
394394
<small>[Try `pitfall2.jsonnet` in Jsonnet Playground](https://jsonnet-libs.github.io/playground/?code=bG9jYWwgd2Vic2VydmVyID0gewogIGxvY2FsIGJhc2UgPSBzZWxmLAoKICBfY29uZmlnOjogewogICAgbmFtZTogZXJyb3IgJ3Byb3ZpZGUgbmFtZScsCiAgICByZXBsaWNhczogMSwKICB9LAoKICBfaW1hZ2VzOjogewogICAgaHR0cGQ6ICdodHRwZDoyLjQnLAogIH0sCgogIGNvbnRhaW5lcjo6IHsKICAgIG5hbWU6ICdodHRwZCcsCiAgICBpbWFnZTogYmFzZS5faW1hZ2VzLmh0dHBkLAogIH0sCgogIGRlcGxveW1lbnQ6IHsKICAgIGFwaVZlcnNpb246ICdhcHBzL3YxJywKICAgIGtpbmQ6ICdEZXBsb3ltZW50JywKICAgIG1ldGFkYXRhOiB7CiAgICAgIG5hbWU6IGJhc2UuX2NvbmZpZy5uYW1lLAogICAgfSwKICAgIHNwZWM6IHsKICAgICAgcmVwbGljYXM6IGJhc2UuX2NvbmZpZy5yZXBsaWNhcywKICAgICAgdGVtcGxhdGU6IHsKICAgICAgICBzcGVjOiB7CiAgICAgICAgICBjb250YWluZXJzOiBbCiAgICAgICAgICAgIGJhc2UuY29udGFpbmVyLAogICAgICAgICAgXSwKICAgICAgICB9LAogICAgICB9LAogICAgfSwKICB9LAp9OwoKd2Vic2VydmVyIHsKICBfY29uZmlnKzogewogICAgbmFtZTogJ3dvbmRlcmZ1bC13ZWJzZXJ2ZXInLAogIH0sCiAgX2ltYWdlcys6IHsKICAgIGh0dHBkOiAnaHR0cGQ6Mi41JywKICB9LAp9Cg==)</small>
395395

396396
This convention attempts to provide a 'stable' API through the `_config` and `_images`
@@ -408,7 +408,7 @@ either way.
408408
This pattern also has an impact on extensibility. When introducing a new attribute, the
409409
author needs to take into account that users might not want the same default.
410410

411-
```jsonnet
411+
~~~jsonnet
412412
local webserver = {
413413
local base = self,
414414
@@ -461,7 +461,7 @@ webserver {
461461
}
462462
463463
// pitfall3.jsonnet
464-
```
464+
~~~
465465
<small>[Try `pitfall3.jsonnet` in Jsonnet Playground](https://jsonnet-libs.github.io/playground/?code=bG9jYWwgd2Vic2VydmVyID0gewogIGxvY2FsIGJhc2UgPSBzZWxmLAoKICBfY29uZmlnOjogewogICAgbmFtZTogZXJyb3IgJ3Byb3ZpZGUgbmFtZScsCiAgICByZXBsaWNhczogMSwKICAgIGltYWdlUHVsbFBvbGljeTogbnVsbCwKICB9LAoKICBfaW1hZ2VzOjogewogICAgaHR0cGQ6ICdodHRwZDoyLjQnLAogIH0sCgogIGNvbnRhaW5lcjo6IHsKICAgIG5hbWU6ICdodHRwZCcsCiAgICBpbWFnZTogYmFzZS5faW1hZ2VzLmh0dHBkLAogIH0gKyAoCiAgICBpZiBiYXNlLl9jb25maWcuaW1hZ2VQdWxsUG9saWN5ICE9IG51bGwKICAgIHRoZW4geyBpbWFnZVB1bGxQb2xpY3k6IGJhc2UuX2NvbmZpZy5pbWFnZVB1bGxQb2xpY3kgfQogICAgZWxzZSB7fQogICksCgogIGRlcGxveW1lbnQ6IHsKICAgIGFwaVZlcnNpb246ICdhcHBzL3YxJywKICAgIGtpbmQ6ICdEZXBsb3ltZW50JywKICAgIG1ldGFkYXRhOiB7CiAgICAgIG5hbWU6IGJhc2UuX2NvbmZpZy5uYW1lLAogICAgfSwKICAgIHNwZWM6IHsKICAgICAgcmVwbGljYXM6IGJhc2UuX2NvbmZpZy5yZXBsaWNhcywKICAgICAgdGVtcGxhdGU6IHsKICAgICAgICBzcGVjOiB7CiAgICAgICAgICBjb250YWluZXJzOiBbCiAgICAgICAgICAgIGJhc2UuY29udGFpbmVyLAogICAgICAgICAgXSwKICAgICAgICB9LAogICAgICB9LAogICAgfSwKICB9LAp9OwoKd2Vic2VydmVyIHsKICBfY29uZmlnKzogewogICAgbmFtZTogJ3dvbmRlcmZ1bC13ZWJzZXJ2ZXInLAogICAgaW1hZ2VQdWxsUG9saWN5OiAnQWx3YXlzJywKICB9LAogIF9pbWFnZXMrOiB7CiAgICBodHRwZDogJ2h0dHBkOjIuNScsCiAgfSwKfQo=)</small>
466466

467467
This can be accomplished with imperative statements, however these pile up over time and
@@ -474,7 +474,7 @@ be provided.
474474

475475
In the object-oriented library this can be done with a new function:
476476

477-
```jsonnet
477+
~~~jsonnet
478478
local webserver = {
479479
new(name, replicas=1): {
480480
local base = self,
@@ -520,7 +520,7 @@ webserver.new('wonderful-webserver')
520520
+ webserver.withImagePullPolicy()
521521
522522
// example7.jsonnet
523-
```
523+
~~~
524524
<small>[Try `example7.jsonnet` in Jsonnet Playground](https://jsonnet-libs.github.io/playground/?code=bG9jYWwgd2Vic2VydmVyID0gewogIG5ldyhuYW1lLCByZXBsaWNhcz0xKTogewogICAgbG9jYWwgYmFzZSA9IHNlbGYsCgogICAgY29udGFpbmVyOjogewogICAgICBuYW1lOiAnaHR0cGQnLAogICAgICBpbWFnZTogJ2h0dHBkOjIuNCcsCiAgICAgIHBvcnRzOiBbewogICAgICAgIGNvbnRhaW5lclBvcnQ6IDgwLAogICAgICB9XSwKICAgIH0sCgogICAgZGVwbG95bWVudDogewogICAgICBhcGlWZXJzaW9uOiAnYXBwcy92MScsCiAgICAgIGtpbmQ6ICdEZXBsb3ltZW50JywKICAgICAgbWV0YWRhdGE6IHsKICAgICAgICBuYW1lOiBuYW1lLAogICAgICB9LAogICAgICBzcGVjOiB7CiAgICAgICAgcmVwbGljYXM6IHJlcGxpY2FzLAogICAgICAgIHRlbXBsYXRlOiB7CiAgICAgICAgICBzcGVjOiB7CiAgICAgICAgICAgIGNvbnRhaW5lcnM6IFsKICAgICAgICAgICAgICBiYXNlLmNvbnRhaW5lciwKICAgICAgICAgICAgXSwKICAgICAgICAgIH0sCiAgICAgICAgfSwKICAgICAgfSwKICAgIH0sCiAgfSwKCiAgd2l0aEltYWdlKGltYWdlKTogewogICAgY29udGFpbmVyKzogeyBpbWFnZTogaW1hZ2UgfSwKICB9LAoKICB3aXRoSW1hZ2VQdWxsUG9saWN5KHBvbGljeT0nQWx3YXlzJyk6IHsKICAgIGNvbnRhaW5lcis6IHsgaW1hZ2VQdWxsUG9saWN5OiBwb2xpY3kgfSwKICB9LAp9OwoKd2Vic2VydmVyLm5ldygnd29uZGVyZnVsLXdlYnNlcnZlcicpCisgd2Vic2VydmVyLndpdGhJbWFnZSgnaHR0cGQ6Mi41JykKKyB3ZWJzZXJ2ZXIud2l0aEltYWdlUHVsbFBvbGljeSgpCg==)</small>
525525

526526
The `withImagePullPolicy()` function provides a more declarative approach to configure
@@ -538,7 +538,7 @@ arguments provides a default value `Always` to get the user going.
538538
As you might have noticed, the `$` keyword is not used in any of these examples. In many
539539
libraries it is used to refer to variables that still need to be set.
540540

541-
```jsonnet
541+
~~~jsonnet
542542
local webserver1 = {
543543
_images:: {
544544
httpd: 'httpd:2.4',
@@ -594,7 +594,7 @@ webserver1 + webserver2 + {
594594
}
595595
596596
// pitfall4.jsonnet
597-
```
597+
~~~
598598
<small>[Try `pitfall4.jsonnet` in Jsonnet Playground](https://jsonnet-libs.github.io/playground/?code=bG9jYWwgd2Vic2VydmVyMSA9IHsKICBfaW1hZ2VzOjogewogICAgaHR0cGQ6ICdodHRwZDoyLjQnLAogIH0sCiAgd2Vic2VydmVyMTogewogICAgYXBpVmVyc2lvbjogJ2FwcHMvdjEnLAogICAga2luZDogJ0RlcGxveW1lbnQnLAogICAgbWV0YWRhdGE6IHsKICAgICAgbmFtZTogJ3dlYnNlcnZlcjEnLAogICAgfSwKICAgIHNwZWM6IHsKICAgICAgcmVwbGljYXM6IDEsCiAgICAgIHRlbXBsYXRlOiB7CiAgICAgICAgc3BlYzogewogICAgICAgICAgY29udGFpbmVyczogW3sKICAgICAgICAgICAgbmFtZTogJ2h0dHBkJywKICAgICAgICAgICAgaW1hZ2U6ICQuX2ltYWdlcy5odHRwZCwKICAgICAgICAgIH1dLAogICAgICAgIH0sCiAgICAgIH0sCiAgICB9LAogIH0sCn07Cgpsb2NhbCB3ZWJzZXJ2ZXIyID0gewogIF9pbWFnZXM6OiB7CiAgICBodHRwZDogJ2h0dHBkOjIuNScsCiAgfSwKICB3ZWJzZXJ2ZXIyOiB7CiAgICBhcGlWZXJzaW9uOiAnYXBwcy92MScsCiAgICBraW5kOiAnRGVwbG95bWVudCcsCiAgICBtZXRhZGF0YTogewogICAgICBuYW1lOiAnd2Vic2VydmVyMicsCiAgICB9LAogICAgc3BlYzogewogICAgICByZXBsaWNhczogJC5fY29uZmlnLmh0dHBkX3JlcGxpY2FzLAogICAgICB0ZW1wbGF0ZTogewogICAgICAgIHNwZWM6IHsKICAgICAgICAgIGNvbnRhaW5lcnM6IFt7CiAgICAgICAgICAgIG5hbWU6ICdodHRwZCcsCiAgICAgICAgICAgIGltYWdlOiAkLl9pbWFnZXMuaHR0cGQsCiAgICAgICAgICB9XSwKICAgICAgICB9LAogICAgICB9LAogICAgfSwKICB9LAp9OwoKd2Vic2VydmVyMSArIHdlYnNlcnZlcjIgKyB7CiAgX2NvbmZpZzo6IHsKICAgIGh0dHBkX3JlcGxpY2FzOiAxLAogIH0sCn0K)</small>
599599

600600
This pattern makes it hard to determine which library is consuming which attribute. On top

‎_gen/lesson2.md

+24-24
Original file line numberDiff line numberDiff line change
@@ -56,13 +56,13 @@ Then "install" a library, [`xtd`](https://github.com/jsonnet-libs/xtd) for examp
5656

5757
To use it, `import` the main file:
5858

59-
```jsonnet
59+
~~~jsonnet
6060
local xtd = import 'github.com/jsonnet-libs/xtd/main.libsonnet';
6161
6262
xtd.ascii.isNumber('2')
6363
6464
// example5/usage1.jsonnet
65-
```
65+
~~~
6666

6767

6868
And finally execute it with:
@@ -79,22 +79,22 @@ hood and how it manipulates these files.
7979
Jsonnet-bundler vendors libraries from Git repositories and tracks them in
8080
`jsonnetfile.json`and its corresponding lockfile `jsonnetfile.lock.json`.
8181

82-
```json
82+
~~~json
8383
{
8484
"version": 1,
8585
"dependencies": [],
8686
"legacyImports": true
8787
}
8888

8989
// example1/jsonnetfile.json
90-
```
90+
~~~
9191

9292

9393
`$ jb init` creates a virtually empty `jsonnetfile.json`.
9494

9595
---
9696

97-
```json
97+
~~~json
9898
{
9999
"version": 1,
100100
"dependencies": [
@@ -112,7 +112,7 @@ Jsonnet-bundler vendors libraries from Git repositories and tracks them in
112112
}
113113

114114
// example2/jsonnetfile.json
115-
```
115+
~~~
116116

117117

118118
`$ jb install github.com/jsonnet-libs/xtd` adds a new entry to the `dependencies` in
@@ -132,7 +132,7 @@ github.com/jsonnet-libs/xtd` will pull in the git commit that `master` refers to
132132

133133
---
134134

135-
```json
135+
~~~json
136136
{
137137
"version": 1,
138138
"dependencies": [
@@ -151,7 +151,7 @@ github.com/jsonnet-libs/xtd` will pull in the git commit that `master` refers to
151151
}
152152

153153
// example2/jsonnetfile.lock.json
154-
```
154+
~~~
155155

156156

157157
A new file `jsonnetfile.lock.json` is created, this contains the actual `version` that
@@ -196,12 +196,12 @@ It is often not necessary and even undesirable to distribute `jsonnetfile.lock.j
196196
pin a specific version (for example when [upstream has breaking
197197
changes](#upstream-has-breaking-changes)).
198198

199-
```gitignore
199+
~~~gitignore
200200
jsonnetfile.lock.json
201201
vendor/
202202
203203
// example3/.gitignore
204-
```
204+
~~~
205205

206206

207207
Add a `.gitignore` file with `jsonnetfile.lock.json` and `vendor/` so they are not
@@ -211,13 +211,13 @@ accidentally committed.
211211

212212
As shown before, to use a library it needs to be imported:
213213

214-
```jsonnet
214+
~~~jsonnet
215215
local xtd = import 'github.com/jsonnet-libs/xtd/main.libsonnet';
216216
217217
xtd.ascii.isNumber('2')
218218
219219
// example5/usage1.jsonnet
220-
```
220+
~~~
221221

222222

223223
Using the long path is the recommended way to import vendored dependencies. It builds on
@@ -229,13 +229,13 @@ cases, the edge cases are covered in [Common use cases](#common-use-cases) below
229229

230230
---
231231

232-
```jsonnet
232+
~~~jsonnet
233233
local xtd = import 'xtd/main.libsonnet';
234234
235235
xtd.ascii.isNumber('2')
236236
237237
// example5/usage2.jsonnet
238-
```
238+
~~~
239239

240240

241241
If `legacyImports` was `true` on install, then the symlink allows to import the library
@@ -293,7 +293,7 @@ A first response may be to ship the `jsonnetfile.lock.json` alongside the librar
293293
this also pins the version of all other libraries, which is often undesirable. It would be
294294
better to pin the version in `jsonnetfile.json`.
295295

296-
```json
296+
~~~json
297297
{
298298
"version": 1,
299299
"dependencies": [
@@ -311,7 +311,7 @@ better to pin the version in `jsonnetfile.json`.
311311
}
312312

313313
// example3/jsonnetfile.json
314-
```
314+
~~~
315315

316316

317317
This can be done by setting tracking `version` on a dependency, you can use `jb install`
@@ -383,7 +383,7 @@ makes it easily distinguishable.
383383

384384
---
385385

386-
```json
386+
~~~json
387387
{
388388
"version": 1,
389389
"dependencies": [
@@ -402,7 +402,7 @@ makes it easily distinguishable.
402402
}
403403

404404
// example4/jsonnetfile.json
405-
```
405+
~~~
406406

407407

408408
Note the `name` attribute on the `dependencies` entry, it has the value of `--legacy-name`
@@ -438,13 +438,13 @@ this library.
438438
439439
---
440440

441-
```jsonnet
441+
~~~jsonnet
442442
local istiolib = import 'istio-lib/main.libsonnet';
443443
444444
istiolib.networking.v1beta1.virtualService.new('test')
445445
446446
// example5/usage3.jsonnet
447-
```
447+
~~~
448448

449449

450450
When using `--legacy-name istio-lib`, the import can look like this.
@@ -454,20 +454,20 @@ When using `--legacy-name istio-lib`, the import can look like this.
454454
Another pattern to naming a dependency with jsonnet-bundler is to create a local library
455455
with the purpose of providing a shortcut.
456456

457-
```jsonnet
457+
~~~jsonnet
458458
(import 'github.com/jsonnet-libs/istio-libsonnet/1.13/main.libsonnet')
459459
460460
// example5/lib/istiolib.libsonnet
461-
```
461+
~~~
462462

463463

464-
```jsonnet
464+
~~~jsonnet
465465
local istiolib = import 'istiolib.libsonnet';
466466
467467
istiolib.networking.v1beta1.virtualService.new('test')
468468
469469
// example5/usage4.jsonnet
470-
```
470+
~~~
471471

472472

473473
The added advantage of this approach is the ability to add local overrides for the library

0 commit comments

Comments
 (0)