Add documentation.yaml for Helio extension builder

README.md

@@ -63,7 +63,7 @@ Reports a random agent from <tt><i>agentset</i></tt>.
 
 The probability of each agent being picked is proportional to the weight given by the <tt><i>reporter</i></tt> for that agent. The weights must not be negative.
 
-If the agentset is empty, it reports [`nobody`](http://ccl.northwestern.edu/netlogo/docs/dictionary.html#nobody).
+If the agentset is empty, it reports [`nobody`](https://docs.netlogo.org/dictionary.html#nobody).
 
 Here is a full rewrite of the **Lottery Example** model using the `rnd:weighted-one-of` primitive:
 
@@ -141,7 +141,7 @@ If all weights are `0.0`, each candidate has an equal probability of being picke
 
 Reports a random item from <tt><i>list</i></tt>.
 
-The probability of each item being picked is proportional to the weight given by the <tt><i>anonymous-reporter</i></tt> for that item. The weights must not be negative. The first argument passed to the anonymous procedure refers to the list item. (See the [Anonymous Procedures section](https://ccl.northwestern.edu/netlogo/docs/programming.html#anonymous-procedures) of the Programming Guide for more details.)
+The probability of each item being picked is proportional to the weight given by the <tt><i>anonymous-reporter</i></tt> for that item. The weights must not be negative. The first argument passed to the anonymous procedure refers to the list item. (See the [Anonymous Procedures section](https://docs.netlogo.org/programming.html#anonymous-procedures) of the Programming Guide for more details.)
 
 It is an error for the list to be empty.
 
@@ -158,15 +158,15 @@ repeat 25 [
 
 This should print `B` roughly four times more often than it prints `A`.
 
-If you happen to have your items and your weights in two separate lists, you can combine them into pairs by using a combination of [`map`](http://ccl.northwestern.edu/netlogo/docs/dictionary.html#map) and [`list`](http://ccl.northwestern.edu/netlogo/docs/dictionary.html#list):
+If you happen to have your items and your weights in two separate lists, you can combine them into pairs by using a combination of [`map`](https://docs.netlogo.org/dictionary.html#map) and [`list`](https://docs.netlogo.org/dictionary.html#list):
 
 ```
 let items [ "A" "B" "C" ]
 let weights [ 0.1 0.2 0.7 ]
 let pairs (map list items weights)
 ```
 
-Since we apply [`map`](http://ccl.northwestern.edu/netlogo/docs/dictionary.html#map) to both the `items` list and the `weights` list, the parentheses are needed in `(map list items weights)`. We also use the concise anonymous procedure syntax (see the [programming guide](http://ccl.northwestern.edu/netlogo/docs/programming.html#anonymous-procedures)) to pass [`list`](http://ccl.northwestern.edu/netlogo/docs/dictionary.html#list) as the reporter for [`map`](http://ccl.northwestern.edu/netlogo/docs/dictionary.html#map). The same thing could have been written `(map [ [a b] -> list a b ] items weights)`.
+Since we apply [`map`](https://docs.netlogo.org/dictionary.html#map) to both the `items` list and the `weights` list, the parentheses are needed in `(map list items weights)`. We also use the concise anonymous procedure syntax (see the [programming guide](https://docs.netlogo.org/programming.html#anonymous-procedures)) to pass [`list`](https://docs.netlogo.org/dictionary.html#list) as the reporter for [`map`](https://docs.netlogo.org/dictionary.html#map). The same thing could have been written `(map [ [a b] -> list a b ] items weights)`.
 
 
 
@@ -180,13 +180,13 @@ Since we apply [`map`](http://ccl.northwestern.edu/netlogo/docs/dictionary.html#
 
 Reports a list of the given <tt><i>size</i></tt> randomly chosen from the <tt><i>list</i></tt> of candidates, with no repeats.
 
-The probability of each item being picked is proportional to the weight given by the <tt><i>anonymous-reporter</i></tt> for that item. The weights must not be negative. The first argument passed to the anonymous procedure refers to the list item. (See the [Anonymous Procedures section](https://ccl.northwestern.edu/netlogo/docs/programming.html#anonymous-procedures) of the Programming Guide for more details.)
+The probability of each item being picked is proportional to the weight given by the <tt><i>anonymous-reporter</i></tt> for that item. The weights must not be negative. The first argument passed to the anonymous procedure refers to the list item. (See the [Anonymous Procedures section](https://docs.netlogo.org/programming.html#anonymous-procedures) of the Programming Guide for more details.)
 
 It is an error for <tt><i>size</i></tt> to be greater than the size of the <tt><i>list</i> of candidates</tt>.
 
 If, at some point during the selection, there remains only candidates with a weight of `0.0`, they all have an equal probability of getting picked.
 
-The items in the resulting list appear in the same order that they appeared in the list of candidates. (If you want them in random order, use [`shuffle`](http://ccl.northwestern.edu/netlogo/docs/dictionary.html#shuffle) on the result).
+The items in the resulting list appear in the same order that they appeared in the list of candidates. (If you want them in random order, use [`shuffle`](https://docs.netlogo.org/dictionary.html#shuffle) on the result).
 
 Example:
 ```
@@ -208,15 +208,15 @@ This should print a list of four numbers, where the bigger numbers (32, 64, 128,
 
 Reports a list of the given <tt><i>size</i></tt> randomly chosen from the <tt><i>list</i></tt> of candidates, with repeats.
 
-The probability of each item being picked is proportional to the weight given by the <tt><i>anonymous-reporter</i></tt> for that item. The weights must not be negative. The first argument passed to the anonymous procedure refers to the list item. (See the [Anonymous Procedures section](https://ccl.northwestern.edu/netlogo/docs/programming.html#anonymous-procedures) of the Programming Guide for more details.)
+The probability of each item being picked is proportional to the weight given by the <tt><i>anonymous-reporter</i></tt> for that item. The weights must not be negative. The first argument passed to the anonymous procedure refers to the list item. (See the [Anonymous Procedures section](https://docs.netlogo.org/programming.html#anonymous-procedures) of the Programming Guide for more details.)
 
 It is **not** an error for <tt><i>size</i></tt> to be greater than the size of the <tt><i>list</i></tt> of candidates, but there has to be at least one candidate.
 
 If, at some point during the selection, there remains only candidates with a weight of `0.0`, they all have an equal probability of getting picked.
 
 If all weights are `0.0`, each candidate has an equal probability of being picked.
 
-The items in the resulting list appear in the same order that they appeared in the list of candidates. (If you want them in random order, use [`shuffle`](http://ccl.northwestern.edu/netlogo/docs/dictionary.html#shuffle) on the result).
+The items in the resulting list appear in the same order that they appeared in the list of candidates. (If you want them in random order, use [`shuffle`](http://docs.netlogo.org/dictionary.html#shuffle) on the result).
 
 Example:
 ```

documentation.yaml

@@ -0,0 +1,226 @@
+extensionName: rnd
+icon: i-mingcute-random-line
+filesToIncludeInManual:
+- USING.md
+- primitives
+markdownTemplate: |2
+
+  # NetLogo `rnd` Extension
+
+  The `rnd` extension comes bundled with NetLogo 6.0 and later. You can find versions the latest version of `rnd` as well as archives of releases compatible with older NetLogo versions [in the project's Github releases page here](https://github.com/NetLogo/Rnd-Extension/releases). Just unzip the file under NetLogo's `extensions/` folder.
+
+  {{> USING.md}}
+
+  ## Primitives
+
+  {{#contents}}{{#prims}}
+  [`{{name}}`](#{{primitive.extensionName}}{{primitive.name}})
+  {{/prims}}{{/contents}}
+
+  {{#primitives}}
+  {{> primTemplate}}
+
+  ***
+
+  {{/primitives}}
+
+  {{> BUILDING.md}}
+  {{> LICENSE.md}}
+primTemplate: |2
+
+  #### `{{name}}`
+
+  {{#examples}}
+  > <div>{{primitive.fullName}}{{#args}} <i>{{name}}</i>{{/args}}</div>
+  {{/examples}}
+
+  {{{description}}}
+primitives:
+- arguments:
+  - type: agentset
+  - name: reporter
+    type: reporter block
+  description: |2
+
+    Reports a random agent from <div><i>agentset</i></div>.
+
+    The probability of each agent being picked is proportional to the weight given by the <div><i>reporter</i></div> for that agent. The weights must not be negative.
+
+    If the agentset is empty, it reports [`nobody`](http://ccl.northwestern.edu/netlogo/docs/dictionary.html#nobody).
+
+    Here is a full rewrite of the **Lottery Example** model using the `rnd:weighted-one-of` primitive:
+
+    ```
+    extensions [ rnd ]
+
+    to setup
+      clear-all
+      ; create a turtle on every fifth patch
+      ask patches with [ pxcor mod 5 = 0 and pycor mod 5 = 0 ] [
+        sprout 1 [
+          set size 2 + random 6 ; vary the size of the turtles
+          set label 0           ; start them out with no wins
+          set color color - 2   ; make turtles darker so the labels stand out
+        ]
+      ]
+      reset-ticks
+    end
+
+    to go
+      ask rnd:weighted-one-of turtles [ size ] [
+        set label label + 1
+      ]
+      tick
+    end
+    ```
+  name: weighted-one-of
+  returns: agent
+  tags:
+  - agentset
+  type: reporter
+- arguments:
+  - name: size
+    type: number
+  - type: agentset
+  - name: '[ reporter ]'
+    type: reporter block
+  description: |2
+
+    Reports an agentset of the given <div><i>size</i></div> randomly chosen from the <div><i>agentset</i></div>, with no repeats.
+
+    The probability of each agent being picked is proportional to the weight given by the <div><i>reporter</i></div> for that agent. The weights must be non-negative numbers.
+
+    It is an error for <div><i>size</i></div> to be greater than the size of the <div><i>agentset</i></div>.
+
+    If, at some point during the selection, there remains only candidates with a weight of `0.0`, they all have an equal probability of getting picked.
+  name: weighted-n-of
+  returns: agentset
+  tags:
+  - agentset
+  type: reporter
+- arguments:
+  - name: size
+    type: number
+  - type: agentset
+  - name: '[ reporter ]'
+    type: reporter block
+  description: |2
+
+    Reports a **list** of the given <div><i>size</i></div> randomly chosen from the <div><i>agentset</i></div>, with repeats. (Why a list instead of an agentset? Because an agentset cannot contain the same agent more than once.)
+
+    The probability of each agent being picked is proportional to the weight given by the <div><i>reporter</i></div> for that agent. The weights must be non-negative numbers.
+
+    It is **not** an error for <div><i>size</i></div> to be greater than the size of the <div><i>agentset</i></div>, but there has to be at least one candidate.
+
+    If, at some point during the selection, there remains only candidates with a weight of `0.0`, they all have an equal probability of getting picked.
+
+    If all weights are `0.0`, each candidate has an equal probability of being picked.
+  name: weighted-n-of-with-repeats
+  returns: list
+  tags:
+  - agentset
+  type: reporter
+- arguments:
+  - type: list
+  - name: anonymous-reporter
+    type: reporter
+  description: |2
+
+    Reports a random item from <div><i>list</i></div>.
+
+    The probability of each item being picked is proportional to the weight given by the <div><i>anonymous-reporter</i></div> for that item. The weights must not be negative. The first argument passed to the anonymous procedure refers to the list item. (See the [Anonymous Procedures section](https://ccl.northwestern.edu/netlogo/docs/programming.html#anonymous-procedures) of the Programming Guide for more details.)
+
+    It is an error for the list to be empty.
+
+    A common way to use the primitive is to have a list of lists, where the first item of each sublist is the thing you want to choose and the second item is the weight. Here is a short example:
+
+    ```
+    let pairs [ [ "A" 0.2 ] [ "B" 0.8 ] ]
+    repeat 25 [
+      ; report the first item of the pair selected using
+      ; the second item (i.e., `last p`) as the weight
+      type first rnd:weighted-one-of-list pairs [ [p] -> last p ]
+    ]
+    ```
+
+    This should print `B` roughly four times more often than it prints `A`.
+
+    If you happen to have your items and your weights in two separate lists, you can combine them into pairs by using a combination of [`map`](http://ccl.northwestern.edu/netlogo/docs/dictionary.html#map) and [`list`](http://ccl.northwestern.edu/netlogo/docs/dictionary.html#list):
+
+    ```
+    let items [ "A" "B" "C" ]
+    let weights [ 0.1 0.2 0.7 ]
+    let pairs (map list items weights)
+    ```
+
+    Since we apply [`map`](http://ccl.northwestern.edu/netlogo/docs/dictionary.html#map) to both the `items` list and the `weights` list, the parentheses are needed in `(map list items weights)`. We also use the concise anonymous procedure syntax (see the [programming guide](http://ccl.northwestern.edu/netlogo/docs/programming.html#anonymous-procedures)) to pass [`list`](http://ccl.northwestern.edu/netlogo/docs/dictionary.html#list) as the reporter for [`map`](http://ccl.northwestern.edu/netlogo/docs/dictionary.html#map). The same thing could have been written `(map [ [a b] -> list a b ] items weights)`.
+  name: weighted-one-of-list
+  returns: anything
+  tags:
+  - list
+  type: reporter
+- arguments:
+  - name: size
+    type: number
+  - type: list
+  - name: anonymous-reporter
+    type: reporter
+  description: |2
+
+    Reports a list of the given <div><i>size</i></div> randomly chosen from the <div><i>list</i></div> of candidates, with no repeats.
+
+    The probability of each item being picked is proportional to the weight given by the <div><i>anonymous-reporter</i></div> for that item. The weights must not be negative. The first argument passed to the anonymous procedure refers to the list item. (See the [Anonymous Procedures section](https://ccl.northwestern.edu/netlogo/docs/programming.html#anonymous-procedures) of the Programming Guide for more details.)
+
+    It is an error for <div><i>size</i></div> to be greater than the size of the <div><i>list</i> of candidates</div>.
+
+    If, at some point during the selection, there remains only candidates with a weight of `0.0`, they all have an equal probability of getting picked.
+
+    The items in the resulting list appear in the same order that they appeared in the list of candidates. (If you want them in random order, use [`shuffle`](http://ccl.northwestern.edu/netlogo/docs/dictionary.html#shuffle) on the result).
+
+    Example:
+    ```
+    let candidates n-values 8 [ [n] -> 2 ^ (n + 1) ] ; make a list with the powers of two
+    print rnd:weighted-n-of-list 4 candidates [ [w] -> w ]
+    ```
+
+    This should print a list of four numbers, where the bigger numbers (32, 64, 128, 256) have a much better chance to show up than the smaller ones (2, 4, 8, 16).
+  name: weighted-n-of-list
+  returns: list
+  tags:
+  - list
+  type: reporter
+- arguments:
+  - name: size
+    type: number
+  - type: list
+  - name: anonymous-reporter
+    type: reporter
+  description: |2
+
+    Reports a list of the given <div><i>size</i></div> randomly chosen from the <div><i>list</i></div> of candidates, with repeats.
+
+    The probability of each item being picked is proportional to the weight given by the <div><i>anonymous-reporter</i></div> for that item. The weights must not be negative. The first argument passed to the anonymous procedure refers to the list item. (See the [Anonymous Procedures section](https://ccl.northwestern.edu/netlogo/docs/programming.html#anonymous-procedures) of the Programming Guide for more details.)
+
+    It is **not** an error for <div><i>size</i></div> to be greater than the size of the <div><i>list</i></div> of candidates, but there has to be at least one candidate.
+
+    If, at some point during the selection, there remains only candidates with a weight of `0.0`, they all have an equal probability of getting picked.
+
+    If all weights are `0.0`, each candidate has an equal probability of being picked.
+
+    The items in the resulting list appear in the same order that they appeared in the list of candidates. (If you want them in random order, use [`shuffle`](http://ccl.northwestern.edu/netlogo/docs/dictionary.html#shuffle) on the result).
+
+    Example:
+    ```
+    let pairs [ [ "A" 0.2 ] [ "B" 0.8 ] ]
+    print map first rnd:weighted-n-of-list-with-repeats 25 pairs [ [p] -> last p ]
+    ```
+
+    This should print a list of 25 `A`s and `B`s, with roughly four times as many `B`s than `A`s.
+  name: weighted-n-of-list-with-repeats
+  returns: list
+  tags:
+  - list
+  type: reporter
+tableOfContents:
+  agentset: AgentSet Primitives
+  list: List Primitives