From 2dd038ea626b8ef6902c62bccb6411e6f763bc67 Mon Sep 17 00:00:00 2001 From: Omar Ibrahim Date: Mon, 17 Nov 2025 13:15:49 -0600 Subject: [PATCH 1/2] Add YAML config for new docs --- README.md | 39 ++++---------- USING.md | 3 +- documentation.yaml | 131 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 141 insertions(+), 32 deletions(-) create mode 100644 documentation.yaml diff --git a/README.md b/README.md index deec586..69168e0 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,3 @@ - # NetLogo Profiler Extension ## Building @@ -49,7 +48,7 @@ profiler:reset ;; clear the data ``` Another way to use the profiler is to export its raw data using -the [`csv` extension](https://ccl.northwestern.edu/netlogo/docs/csv.html) +the [`csv` extension](https://docs.netlogo.org/csv.html) and the `profiler:data` primitive: ```NetLogo @@ -83,7 +82,6 @@ REPRODUCE-WOLVES,1039,5.599509,5.599509 Thanks to Roger Peppe for his contributions to the code. - ## Primitives [`profiler:calls`](#profilercalls) @@ -95,18 +93,14 @@ Thanks to Roger Peppe for his contributions to the code. [`profiler:report`](#profilerreport) [`profiler:data`](#profilerdata) - ### `profiler:calls` ```NetLogo profiler:calls procedure-name ``` - -Reports the number of times that *procedure-name* was called. If -*procedure-name* is not defined, then reports 0. - - +Reports the number of times that _procedure-name_ was called. If +_procedure-name_ is not defined, then reports 0. ### `profiler:exclusive-time` @@ -114,16 +108,13 @@ Reports the number of times that *procedure-name* was called. If profiler:exclusive-time procedure-name ``` - Reports the exclusive time, in milliseconds, that -*procedure-name* was running for. Exclusive time is the time +_procedure-name_ was running for. Exclusive time is the time from when the procedure was entered, until it finishes, but does not include any time spent in other user-defined procedures which it calls. -If *procedure-name* is not defined, then reports 0. - - +If _procedure-name_ is not defined, then reports 0. ### `profiler:inclusive-time` @@ -131,14 +122,11 @@ If *procedure-name* is not defined, then reports 0. profiler:inclusive-time procedure-name ``` - Reports the inclusive time, in milliseconds, that -*procedure-name* was running for. Inclusive time is the time +_procedure-name_ was running for. Inclusive time is the time from when the procedure was entered, until it finishes. -If *procedure-name* is not defined, then reports 0. - - +If _procedure-name_ is not defined, then reports 0. ### `profiler:start` @@ -148,7 +136,6 @@ profiler:start Instructs the profiler to begin recording user-defined procedure calls. - ### `profiler:stop` ```NetLogo @@ -157,7 +144,6 @@ profiler:stop Instructs the profiler to stop recording user-defined procedure calls. - ### `profiler:reset` ```NetLogo @@ -166,14 +152,12 @@ profiler:reset Instructs the profiler to erase all collected data. - ### `profiler:report` ```NetLogo profiler:report ``` - Reports a string containing a breakdown of all user-defined procedure calls. The `Calls` column contains the number of times a user-defined procedure was called. The `Incl T(ms)` column @@ -205,26 +189,21 @@ Name Calls Incl T(ms) Excl T(ms) Excl/calls CALLTHEM 13 26.066 19.476 1.498 ``` - - ### `profiler:data` ```NetLogo profiler:data ``` - Reports a list of lists containing the results of the profiler in a format that is suitable -for exporting with the [`csv` extension](https://ccl.northwestern.edu/netlogo/docs/csv.html). +for exporting with the [`csv` extension](/csv). The first sublist contains the name of the data columns: `procedure`, `calls`, `inclusive_time` and `exclusive_time`. This is followed by one sublist containing the profiler data for each user-defined procedure. The reported times are in milliseconds. - - ## Terms of Use [![CC0](http://i.creativecommons.org/p/zero/1.0/88x31.png)](http://creativecommons.org/publicdomain/zero/1.0/) -The NetLogo profiler extension is in the public domain. To the extent possible under law, Uri Wilensky has waived all copyright and related or neighboring rights. +The NetLogo profiler extension is in the public domain. To the extent possible under law, Uri Wilensky has waived all copyright and related or neighboring rights. diff --git a/USING.md b/USING.md index 419ee5d..9740118 100644 --- a/USING.md +++ b/USING.md @@ -38,7 +38,7 @@ profiler:reset ;; clear the data ``` Another way to use the profiler is to export its raw data using -the [`csv` extension](https://ccl.northwestern.edu/netlogo/docs/csv.html) +the [`csv` extension](https://docs.netlogo.org/csv.html) and the `profiler:data` primitive: ```NetLogo @@ -71,4 +71,3 @@ REPRODUCE-WOLVES,1039,5.599509,5.599509 ``` Thanks to Roger Peppe for his contributions to the code. - diff --git a/documentation.yaml b/documentation.yaml new file mode 100644 index 0000000..b87beb2 --- /dev/null +++ b/documentation.yaml @@ -0,0 +1,131 @@ +extensionName: profiler +icon: i-oui-app-search-profiler +filesToIncludeInManual: +- USING.md +- primitives +markdownTemplate: |2 + + # NetLogo Profiler Extension + + {{> BUILDING.md}} + + {{> USING.md}} + + ## Primitives + + {{#contents}}{{#prims}} + [`{{name}}`](#{{primitive.extensionName}}{{primitive.name}}) + {{/prims}}{{/contents}} + + {{#primitives}} + {{> primTemplate}} + {{/primitives}} + + {{> LICENSE.md}} +primTemplate: |2 + + ### `{{name}}` + + ```NetLogo + {{#examples}} + {{primitive.fullName}}{{#args}} {{name}}{{/args}} + {{/examples}} + ``` + + {{{description}}} +primitives: + - name: calls + type: reporter + returns: number + arguments: + - name: procedure-name + type: string + description: | + Reports the number of times that *procedure-name* was called. If + *procedure-name* is not defined, then reports 0. + + - name: exclusive-time + type: reporter + returns: number + arguments: + - name: procedure-name + type: string + description: | + Reports the exclusive time, in milliseconds, that + *procedure-name* was running for. Exclusive time is the time + from when the procedure was entered, until it finishes, but does not + include any time spent in other user-defined procedures which it + calls. + + If *procedure-name* is not defined, then reports 0. + + - name: inclusive-time + type: reporter + returns: number + arguments: + - name: procedure-name + type: string + description: | + Reports the inclusive time, in milliseconds, that + *procedure-name* was running for. Inclusive time is the time + from when the procedure was entered, until it finishes. + + If *procedure-name* is not defined, then reports 0. + + - name: start + type: command + description: Instructs the profiler to begin recording user-defined procedure calls. + + - name: stop + type: command + description: Instructs the profiler to stop recording user-defined procedure calls. + + - name: reset + type: command + description: Instructs the profiler to erase all collected data. + + - name: report + type: reporter + returns: string + description: | + Reports a string containing a breakdown of all user-defined procedure + calls. The `Calls` column contains the number of times a + user-defined procedure was called. The `Incl T(ms)` column + is the total time, in milliseconds, it took for the call to complete, + including the time spent in other user-defined procedures. The + `Excl T(ms)` column is the total time, in milliseconds, + spent within that user-defined procedure, not counting other + user-define procedures it called. The Excl/calls column + is an estimate of the time, in milliseconds, spent in that + user-defined procedure for each call. + + Here is example output: + + ``` + Sorted by Exclusive Time + Name Calls Incl T(ms) Excl T(ms) Excl/calls + CALLTHEM 13 26.066 19.476 1.498 + CALLME 13 6.413 6.413 0.493 + REPORTME 13 0.177 0.177 0.014 + + Sorted by Inclusive Time + Name Calls Incl T(ms) Excl T(ms) Excl/calls + CALLTHEM 13 26.066 19.476 1.498 + CALLME 13 6.413 6.413 0.493 + REPORTME 13 0.177 0.177 0.014 + + Sorted by Number of Calls + Name Calls Incl T(ms) Excl T(ms) Excl/calls + CALLTHEM 13 26.066 19.476 1.498 + ``` + + - name: data + type: reporter + returns: list + description: | + Reports a list of lists containing the results of the profiler in a format that is suitable + for exporting with the [`csv` extension](https://ccl.northwestern.edu/netlogo/docs/csv.html). + + The first sublist contains the name of the data columns: `procedure`, `calls`, `inclusive_time` and + `exclusive_time`. This is followed by one sublist containing the profiler data for each user-defined + procedure. The reported times are in milliseconds. From f4539e27398ea576b55cebfb2651f78993ca5c80 Mon Sep 17 00:00:00 2001 From: Omar Ibrahim Date: Fri, 21 Nov 2025 12:12:36 -0600 Subject: [PATCH 2/2] add documentation.yaml --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 69168e0..3daa145 100644 --- a/README.md +++ b/README.md @@ -196,7 +196,7 @@ profiler:data ``` Reports a list of lists containing the results of the profiler in a format that is suitable -for exporting with the [`csv` extension](/csv). +for exporting with the [`csv` extension](https://docs.netlogo.org/csv.html). The first sublist contains the name of the data columns: `procedure`, `calls`, `inclusive_time` and `exclusive_time`. This is followed by one sublist containing the profiler data for each user-defined