Fix docstring extraction to use inspect.cleandoc for proper indentation

Author: milanofthe

scripts/extract.py

@@ -50,9 +50,12 @@ def rst_to_html(rst_text: str) -> str:
     if not rst_text or not HAS_DOCUTILS:
         return ""
 
+    # Clean the docstring - removes common leading whitespace from indented docstrings
+    cleaned = inspect.cleandoc(rst_text)
+
     try:
         parts = publish_parts(
-            rst_text,
+            cleaned,
             writer_name="html",
             settings_overrides={
                 "report_level": 5,

src/lib/events/generated/events.ts

@@ -10,7 +10,7 @@ export const extractedEvents: EventTypeDefinition[] =
     "name": "ZeroCrossing",
     "eventClass": "ZeroCrossing",
     "description": "Subclass of base 'Event' that triggers if the event function crosses zero.",
-    "docstringHtml": "<p>Subclass of base 'Event' that triggers if the event function crosses zero.\nThis is a bidirectional zero-crossing detector.</p>\n<p>Monitors system state by evaluating an event function (func_evt) with scalar output and\ntesting for zero crossings (sign changes).</p>\n<pre class=\"code literal-block\">\nfunc_evt(time) -&gt; event?\n</pre>\n<p>If an event is detected, some action (func_act) is performed on the system state.</p>\n<pre class=\"code literal-block\">\nfunc_evt(time) == 0 -&gt; event -&gt; func_act(time)\n</pre>\n<div class=\"section\" id=\"example\">\n<h3>Example</h3>\n<p>Initialize a zero-crossing event handler like this:</p>\n<pre class=\"code python literal-block\">\n# define the event function\ndef evt(t):\n    # here we have a zero-crossing at 't==10'\n    return t - 10\n\n# define the action function (callback)\ndef act(t):\n    # do something at event resolution\n    pass\n\n# initialize the event manager\nE = ZeroCrossing(\n    func_evt=evt,  # the event function\n    func_act=act   # the action function\n    )\n</pre>\n</div>\n<div class=\"section\" id=\"parameters\">\n<h3>Parameters</h3>\n<dl class=\"docutils\">\n<dt>func_evt <span class=\"classifier-delimiter\">:</span> <span class=\"classifier\">callable</span></dt>\n<dd>event function, where zeros are events</dd>\n<dt>func_act <span class=\"classifier-delimiter\">:</span> <span class=\"classifier\">callable</span></dt>\n<dd>action function for event resolution</dd>\n<dt>tolerance <span class=\"classifier-delimiter\">:</span> <span class=\"classifier\">float</span></dt>\n<dd>tolerance to check if detection is close to actual event</dd>\n</dl>\n</div>\n",
+    "docstringHtml": "<p>Subclass of base 'Event' that triggers if the event function crosses zero.\nThis is a bidirectional zero-crossing detector.</p>\n<p>Monitors system state by evaluating an event function (func_evt) with scalar output and\ntesting for zero crossings (sign changes).</p>\n<pre class=\"code literal-block\">\nfunc_evt(time) -&gt; event?\n</pre>\n<p>If an event is detected, some action (func_act) is performed on the system state.</p>\n<pre class=\"code literal-block\">\nfunc_evt(time) == 0 -&gt; event -&gt; func_act(time)\n</pre>\n<div class=\"section\" id=\"example\">\n<h3>Example</h3>\n<p>Initialize a zero-crossing event handler like this:</p>\n<pre class=\"code python literal-block\">\n<span class=\"comment single\">#define the event function</span><span class=\"whitespace\">\n</span><span class=\"keyword\">def</span><span class=\"whitespace\"> </span><span class=\"name function\">evt</span><span class=\"punctuation\">(</span><span class=\"name\">t</span><span class=\"punctuation\">):</span><span class=\"whitespace\">\n</span>    <span class=\"comment single\">#here we have a zero-crossing at 't==10'</span><span class=\"whitespace\">\n</span>    <span class=\"keyword\">return</span> <span class=\"name\">t</span> <span class=\"operator\">-</span> <span class=\"literal number integer\">10</span><span class=\"whitespace\">\n\n</span><span class=\"comment single\">#define the action function (callback)</span><span class=\"whitespace\">\n</span><span class=\"keyword\">def</span><span class=\"whitespace\"> </span><span class=\"name function\">act</span><span class=\"punctuation\">(</span><span class=\"name\">t</span><span class=\"punctuation\">):</span><span class=\"whitespace\">\n</span>    <span class=\"comment single\">#do something at event resolution</span><span class=\"whitespace\">\n</span>    <span class=\"keyword\">pass</span><span class=\"whitespace\">\n\n</span><span class=\"comment single\">#initialize the event manager</span><span class=\"whitespace\">\n</span><span class=\"name\">E</span> <span class=\"operator\">=</span> <span class=\"name\">ZeroCrossing</span><span class=\"punctuation\">(</span><span class=\"whitespace\">\n</span>    <span class=\"name\">func_evt</span><span class=\"operator\">=</span><span class=\"name\">evt</span><span class=\"punctuation\">,</span>  <span class=\"comment single\">#the event function</span><span class=\"whitespace\">\n</span>    <span class=\"name\">func_act</span><span class=\"operator\">=</span><span class=\"name\">act</span>   <span class=\"comment single\">#the action function</span><span class=\"whitespace\">\n</span>    <span class=\"punctuation\">)</span>\n</pre>\n</div>\n<div class=\"section\" id=\"parameters\">\n<h3>Parameters</h3>\n<dl class=\"docutils\">\n<dt>func_evt <span class=\"classifier-delimiter\">:</span> <span class=\"classifier\">callable</span></dt>\n<dd>event function, where zeros are events</dd>\n<dt>func_act <span class=\"classifier-delimiter\">:</span> <span class=\"classifier\">callable</span></dt>\n<dd>action function for event resolution</dd>\n<dt>tolerance <span class=\"classifier-delimiter\">:</span> <span class=\"classifier\">float</span></dt>\n<dd>tolerance to check if detection is close to actual event</dd>\n</dl>\n</div>\n",
     "params": [
       {
         "name": "func_evt",
@@ -91,7 +91,7 @@ export const extractedEvents: EventTypeDefinition[] =
     "name": "Schedule",
     "eventClass": "Schedule",
     "description": "Subclass of base 'Event' that triggers dependent on the evaluation time.",
-    "docstringHtml": "<p>Subclass of base 'Event' that triggers dependent on the evaluation time.</p>\n<p>Monitors time in every timestep and triggers periodically (period). This event\ndoes not have an event function as the event condition only depends on time.</p>\n<pre class=\"code literal-block\">\ntime == next_schedule_time -&gt; event\n</pre>\n<div class=\"section\" id=\"example\">\n<h3>Example</h3>\n<p>Initialize a scheduled event handler like this:</p>\n<pre class=\"code python literal-block\">\n#define the action function (callback)\ndef act(t):\n    #do something at event resolution\n    pass\n\n#initialize the event manager\nE = Schedule(\n    t_start=0,    #starting at t=0\n    t_end=None,   #never ending\n    t_period=3,   #triggering every 3 time units\n    func_act=act  #resulting in a callback\n    )\n</pre>\n</div>\n<div class=\"section\" id=\"parameters\">\n<h3>Parameters</h3>\n<dl class=\"docutils\">\n<dt>t_start <span class=\"classifier-delimiter\">:</span> <span class=\"classifier\">float</span></dt>\n<dd>starting time for schedule</dd>\n<dt>t_end <span class=\"classifier-delimiter\">:</span> <span class=\"classifier\">float</span></dt>\n<dd>termination time for schedule</dd>\n<dt>t_period <span class=\"classifier-delimiter\">:</span> <span class=\"classifier\">float</span></dt>\n<dd>time period of schedule, when events are triggered</dd>\n<dt>func_act <span class=\"classifier-delimiter\">:</span> <span class=\"classifier\">callable</span></dt>\n<dd>action function for event resolution</dd>\n<dt>tolerance <span class=\"classifier-delimiter\">:</span> <span class=\"classifier\">float</span></dt>\n<dd>tolerance to check if detection is close to actual event</dd>\n</dl>\n</div>\n",
+    "docstringHtml": "<p>Subclass of base 'Event' that triggers dependent on the evaluation time.</p>\n<p>Monitors time in every timestep and triggers periodically (period). This event\ndoes not have an event function as the event condition only depends on time.</p>\n<pre class=\"code literal-block\">\ntime == next_schedule_time -&gt; event\n</pre>\n<div class=\"section\" id=\"example\">\n<h3>Example</h3>\n<p>Initialize a scheduled event handler like this:</p>\n<pre class=\"code python literal-block\">\n<span class=\"comment single\">#define the action function (callback)</span><span class=\"whitespace\">\n</span><span class=\"keyword\">def</span><span class=\"whitespace\"> </span><span class=\"name function\">act</span><span class=\"punctuation\">(</span><span class=\"name\">t</span><span class=\"punctuation\">):</span><span class=\"whitespace\">\n</span>    <span class=\"comment single\">#do something at event resolution</span><span class=\"whitespace\">\n</span>    <span class=\"keyword\">pass</span><span class=\"whitespace\">\n\n</span><span class=\"comment single\">#initialize the event manager</span><span class=\"whitespace\">\n</span><span class=\"name\">E</span> <span class=\"operator\">=</span> <span class=\"name\">Schedule</span><span class=\"punctuation\">(</span><span class=\"whitespace\">\n</span>    <span class=\"name\">t_start</span><span class=\"operator\">=</span><span class=\"literal number integer\">0</span><span class=\"punctuation\">,</span>    <span class=\"comment single\">#starting at t=0</span><span class=\"whitespace\">\n</span>    <span class=\"name\">t_end</span><span class=\"operator\">=</span><span class=\"keyword constant\">None</span><span class=\"punctuation\">,</span>   <span class=\"comment single\">#never ending</span><span class=\"whitespace\">\n</span>    <span class=\"name\">t_period</span><span class=\"operator\">=</span><span class=\"literal number integer\">3</span><span class=\"punctuation\">,</span>   <span class=\"comment single\">#triggering every 3 time units</span><span class=\"whitespace\">\n</span>    <span class=\"name\">func_act</span><span class=\"operator\">=</span><span class=\"name\">act</span>  <span class=\"comment single\">#resulting in a callback</span><span class=\"whitespace\">\n</span>    <span class=\"punctuation\">)</span>\n</pre>\n</div>\n<div class=\"section\" id=\"parameters\">\n<h3>Parameters</h3>\n<dl class=\"docutils\">\n<dt>t_start <span class=\"classifier-delimiter\">:</span> <span class=\"classifier\">float</span></dt>\n<dd>starting time for schedule</dd>\n<dt>t_end <span class=\"classifier-delimiter\">:</span> <span class=\"classifier\">float</span></dt>\n<dd>termination time for schedule</dd>\n<dt>t_period <span class=\"classifier-delimiter\">:</span> <span class=\"classifier\">float</span></dt>\n<dd>time period of schedule, when events are triggered</dd>\n<dt>func_act <span class=\"classifier-delimiter\">:</span> <span class=\"classifier\">callable</span></dt>\n<dd>action function for event resolution</dd>\n<dt>tolerance <span class=\"classifier-delimiter\">:</span> <span class=\"classifier\">float</span></dt>\n<dd>tolerance to check if detection is close to actual event</dd>\n</dl>\n</div>\n",
     "params": [
       {
         "name": "t_start",
@@ -130,7 +130,7 @@ export const extractedEvents: EventTypeDefinition[] =
     "name": "ScheduleList",
     "eventClass": "ScheduleList",
     "description": "Subclass of base 'Schedule' that triggers dependent on the evaluation time.",
-    "docstringHtml": "<p>Subclass of base 'Schedule' that triggers dependent on the evaluation time.</p>\n<p>Monitors time in every timestep and triggers at the next event time from the\ntime list. This event does not have an event function as the event condition\nonly depends on time.</p>\n<pre class=\"code literal-block\">\ntime == next_scheduled_time -&gt; event\n</pre>\n<div class=\"section\" id=\"example\">\n<h3>Example</h3>\n<p>Initialize a scheduled event handler like this:</p>\n<pre class=\"code python literal-block\">\n#define the action function (callback)\ndef act(t):\n    #do something at event resolution\n    pass\n\n#initialize the event manager\nE = ScheduleList(\n    times_evt=[1, 5, 12, 300],  #event times where to trigger\n    func_act=act                #resulting in a callback\n    )\n</pre>\n</div>\n<div class=\"section\" id=\"parameters\">\n<h3>Parameters</h3>\n<dl class=\"docutils\">\n<dt>times_evt <span class=\"classifier-delimiter\">:</span> <span class=\"classifier\">list[float]</span></dt>\n<dd>list of event times in ascending order</dd>\n<dt>func_act <span class=\"classifier-delimiter\">:</span> <span class=\"classifier\">callable</span></dt>\n<dd>action function for event resolution</dd>\n<dt>tolerance <span class=\"classifier-delimiter\">:</span> <span class=\"classifier\">float</span></dt>\n<dd>tolerance to check if detection is close to actual event</dd>\n</dl>\n</div>\n",
+    "docstringHtml": "<p>Subclass of base 'Schedule' that triggers dependent on the evaluation time.</p>\n<p>Monitors time in every timestep and triggers at the next event time from the\ntime list. This event does not have an event function as the event condition\nonly depends on time.</p>\n<pre class=\"code literal-block\">\ntime == next_scheduled_time -&gt; event\n</pre>\n<div class=\"section\" id=\"example\">\n<h3>Example</h3>\n<p>Initialize a scheduled event handler like this:</p>\n<pre class=\"code python literal-block\">\n<span class=\"comment single\">#define the action function (callback)</span><span class=\"whitespace\">\n</span><span class=\"keyword\">def</span><span class=\"whitespace\"> </span><span class=\"name function\">act</span><span class=\"punctuation\">(</span><span class=\"name\">t</span><span class=\"punctuation\">):</span><span class=\"whitespace\">\n</span>    <span class=\"comment single\">#do something at event resolution</span><span class=\"whitespace\">\n</span>    <span class=\"keyword\">pass</span><span class=\"whitespace\">\n\n</span><span class=\"comment single\">#initialize the event manager</span><span class=\"whitespace\">\n</span><span class=\"name\">E</span> <span class=\"operator\">=</span> <span class=\"name\">ScheduleList</span><span class=\"punctuation\">(</span><span class=\"whitespace\">\n</span>    <span class=\"name\">times_evt</span><span class=\"operator\">=</span><span class=\"punctuation\">[</span><span class=\"literal number integer\">1</span><span class=\"punctuation\">,</span> <span class=\"literal number integer\">5</span><span class=\"punctuation\">,</span> <span class=\"literal number integer\">12</span><span class=\"punctuation\">,</span> <span class=\"literal number integer\">300</span><span class=\"punctuation\">],</span>  <span class=\"comment single\">#event times where to trigger</span><span class=\"whitespace\">\n</span>    <span class=\"name\">func_act</span><span class=\"operator\">=</span><span class=\"name\">act</span>                <span class=\"comment single\">#resulting in a callback</span><span class=\"whitespace\">\n</span>    <span class=\"punctuation\">)</span>\n</pre>\n</div>\n<div class=\"section\" id=\"parameters\">\n<h3>Parameters</h3>\n<dl class=\"docutils\">\n<dt>times_evt <span class=\"classifier-delimiter\">:</span> <span class=\"classifier\">list[float]</span></dt>\n<dd>list of event times in ascending order</dd>\n<dt>func_act <span class=\"classifier-delimiter\">:</span> <span class=\"classifier\">callable</span></dt>\n<dd>action function for event resolution</dd>\n<dt>tolerance <span class=\"classifier-delimiter\">:</span> <span class=\"classifier\">float</span></dt>\n<dd>tolerance to check if detection is close to actual event</dd>\n</dl>\n</div>\n",
     "params": [
       {
         "name": "times_evt",
@@ -157,7 +157,7 @@ export const extractedEvents: EventTypeDefinition[] =
     "name": "Condition",
     "eventClass": "Condition",
     "description": "Subclass of base 'Event' that triggers if the event function evaluates to 'True',",
-    "docstringHtml": "<p>Subclass of base 'Event' that triggers if the event function evaluates to 'True',\ni.e. the condition is satisfied.</p>\n<p>Monitors system state by evaluating an event function (func_evt) with boolean output.\nThe event is considered detected when the event function evaluates to 'True' for the\nfirst time. Subsequent evaluations to 'True' are not considered unless the event is reset.</p>\n<pre class=\"code literal-block\">\nfunc_evt(time) -&gt; event?\n</pre>\n<p>If an event is detected, some action (func_act) is performed on the system state.</p>\n<pre class=\"code literal-block\">\nfunc_evt(time) == True -&gt; event -&gt; func_act(time)\n</pre>\n<div class=\"section\" id=\"note\">\n<h3>Note</h3>\n<p>Condition event functions evaluate to boolean and are therefore not smooth.\nTherefore uses bisection method for event location instead of secant method.</p>\n</div>\n<div class=\"section\" id=\"example\">\n<h3>Example</h3>\n<p>Initialize a conditional event handler like this:</p>\n<pre class=\"code python literal-block\">\n#define the event function\ndef evt(t):\n    return t &gt; 10\n\n#define the action function (callback)\ndef act(t):\n    #do something at event resolution\n    pass\n\n#initialize the event manager\nE = Condition(\n    func_evt=evt,  #the event function\n    func_act=act   #the action function\n    )\n</pre>\n</div>\n",
+    "docstringHtml": "<p>Subclass of base 'Event' that triggers if the event function evaluates to 'True',\ni.e. the condition is satisfied.</p>\n<p>Monitors system state by evaluating an event function (func_evt) with boolean output.\nThe event is considered detected when the event function evaluates to 'True' for the\nfirst time. Subsequent evaluations to 'True' are not considered unless the event is reset.</p>\n<pre class=\"code literal-block\">\nfunc_evt(time) -&gt; event?\n</pre>\n<p>If an event is detected, some action (func_act) is performed on the system state.</p>\n<pre class=\"code literal-block\">\nfunc_evt(time) == True -&gt; event -&gt; func_act(time)\n</pre>\n<div class=\"section\" id=\"note\">\n<h3>Note</h3>\n<p>Condition event functions evaluate to boolean and are therefore not smooth.\nTherefore uses bisection method for event location instead of secant method.</p>\n</div>\n<div class=\"section\" id=\"example\">\n<h3>Example</h3>\n<p>Initialize a conditional event handler like this:</p>\n<pre class=\"code python literal-block\">\n<span class=\"comment single\">#define the event function</span><span class=\"whitespace\">\n</span><span class=\"keyword\">def</span><span class=\"whitespace\"> </span><span class=\"name function\">evt</span><span class=\"punctuation\">(</span><span class=\"name\">t</span><span class=\"punctuation\">):</span><span class=\"whitespace\">\n</span>    <span class=\"keyword\">return</span> <span class=\"name\">t</span> <span class=\"operator\">&gt;</span> <span class=\"literal number integer\">10</span><span class=\"whitespace\">\n\n</span><span class=\"comment single\">#define the action function (callback)</span><span class=\"whitespace\">\n</span><span class=\"keyword\">def</span><span class=\"whitespace\"> </span><span class=\"name function\">act</span><span class=\"punctuation\">(</span><span class=\"name\">t</span><span class=\"punctuation\">):</span><span class=\"whitespace\">\n</span>    <span class=\"comment single\">#do something at event resolution</span><span class=\"whitespace\">\n</span>    <span class=\"keyword\">pass</span><span class=\"whitespace\">\n\n</span><span class=\"comment single\">#initialize the event manager</span><span class=\"whitespace\">\n</span><span class=\"name\">E</span> <span class=\"operator\">=</span> <span class=\"name\">Condition</span><span class=\"punctuation\">(</span><span class=\"whitespace\">\n</span>    <span class=\"name\">func_evt</span><span class=\"operator\">=</span><span class=\"name\">evt</span><span class=\"punctuation\">,</span>  <span class=\"comment single\">#the event function</span><span class=\"whitespace\">\n</span>    <span class=\"name\">func_act</span><span class=\"operator\">=</span><span class=\"name\">act</span>   <span class=\"comment single\">#the action function</span><span class=\"whitespace\">\n</span>    <span class=\"punctuation\">)</span>\n</pre>\n</div>\n",
     "params": [
       {
         "name": "func_evt",