workaround with docs

assets/src/ba_data/python/._ba_sources_hash

@@ -1 +1 @@
-142084453862763162635228312125641718455
+175217515325031448193730963697929841246

assets/src/ba_data/python/_ba.py

@@ -235,41 +235,41 @@ class InputDevice:
 
     Attributes:
 
-       allows_configuring: bool
+       allows_configuring
           Whether the input-device can be configured.
 
-       has_meaningful_button_names: bool
+       has_meaningful_button_names
           Whether button names returned by this instance match labels
           on the actual device. (Can be used to determine whether to show
-          them in controls-overlays, etc.)
+          them in controls-overlays, etc.).
 
-       player: Optional[ba.SessionPlayer]
+       player
           The player associated with this input device.
 
-       client_id: int
+       client_id
           The numeric client-id this device is associated with.
           This is only meaningful for remote client inputs; for
           all local devices this will be -1.
 
-       name: str
+       name
           The name of the device.
 
-       unique_identifier: str
+       unique_identifier
           A string that can be used to persistently identify the device,
           even among other devices of the same type. Used for saving
           prefs, etc.
 
-       id: int
+       id
           The unique numeric id of this device.
 
-       instance_number: int
+       instance_number
           The number of this device among devices of the same type.
 
-       is_controller_app: bool
+       is_controller_app
           Whether this input-device represents a locally-connected
           controller-app.
 
-       is_remote_client: bool
+       is_remote_client
           Whether this input-device represents a remotely-connected
           client.
 
@@ -375,7 +375,7 @@ class Material:
 
     Attributes:
 
-        label: str
+        label
             A label for the material; only used for debugging.
     """
 
@@ -839,14 +839,6 @@ class SessionPlayer:
         activityplayer: Optional[ba.Player]
             The current game-specific instance for this player.
     """
-    id: int
-    in_game: bool
-    sessionteam: ba.SessionTeam
-    inputdevice: ba.InputDevice
-    color: Sequence[float]
-    highlight: Sequence[float]
-    character: str
-    activityplayer: Optional[ba.Player]
 
     def assigninput(self, type: Union[ba.InputType, tuple[ba.InputType, ...]],
                     call: Callable) -> None:
@@ -1056,9 +1048,6 @@ class Vec3(Sequence[float]):
        z: float
           The vector's Z component.
     """
-    x: float
-    y: float
-    z: float
 
     # pylint: disable=function-redefined
 

assets/src/ba_data/python/ba/_general.py

@@ -150,24 +150,25 @@ class _WeakCall:
     Think of this as a handy way to tell an object to do something
     at some point in the future if it happens to still exist.
 
-    # EXAMPLE A: this code will create a FooClass instance and call its
+    Examples:
-    # bar() method 5 seconds later; it will be kept alive even though
+        EXAMPLE A: this code will create a FooClass instance and call its
-    # we overwrite its variable with None because the bound method
+        bar() method 5 seconds later; it will be kept alive even though
-    # we pass as a timer callback (foo.bar) strong-references it
+        we overwrite its variable with None because the bound method
-    foo = FooClass()
+        we pass as a timer callback (foo.bar) strong-references it
-    ba.timer(5.0, foo.bar)
+        >>> foo = FooClass()
-    foo = None
+        ... ba.timer(5.0, foo.bar)
+        ... foo = None
 
-    # EXAMPLE B: this code will *not* keep our object alive; it will die
+        EXAMPLE B: this code will *not* keep our object alive; it will die
-    # when we overwrite it with None and the timer will be a no-op when it
+        when we overwrite it with None and the timer will be a no-op when it
-    # fires
+        fires
-    foo = FooClass()
+        >>> foo = FooClass()
-    ba.timer(5.0, ba.WeakCall(foo.bar))
+        ... ba.timer(5.0, ba.WeakCall(foo.bar))
-    foo = None
+        ... foo = None
 
-    Note: additional args and keywords you provide to the WeakCall()
+        Note: additional args and keywords you provide to the WeakCall()
-    constructor are stored as regular strong-references; you'll need
+        constructor are stored as regular strong-references; you'll need
-    to wrap them in weakrefs manually if desired.
+        to wrap them in weakrefs manually if desired.
     """
 
     def __init__(self, *args: Any, **keywds: Any) -> None:
@@ -176,14 +177,16 @@ class _WeakCall:
         Pass a callable as the first arg, followed by any number of
         arguments or keywords.
 
-        # Example: wrap a method call with some positional and
+        Examples:
-        # keyword args:
+            Example: wrap a method call with some positional and
-        myweakcall = ba.WeakCall(myobj.dostuff, argval1, namedarg=argval2)
+            keyword args:
-
+            >>> myweakcall = ba.WeakCall(myobj.dostuff, argval1,
-        # Now we have a single callable to run that whole mess.
+            ...                          namedarg=argval2)
-        # The same as calling myobj.dostuff(argval1, namedarg=argval2)
+            ... # Now we have a single callable to run that whole mess.
-        # (provided my_obj still exists; this will do nothing otherwise)
+            ... # The same as calling myobj.dostuff(argval1, namedarg=argval2)
-        myweakcall()
+            ... # (provided my_obj still exists; this will do nothing
+            ... # otherwise).
+            ... myweakcall()
         """
         if hasattr(args[0], '__func__'):
             self._call = WeakMethod(args[0])
@@ -217,8 +220,8 @@ class _Call:
     The callable is strong-referenced so it won't die until this
     object does.
 
-    Note that a bound method (ex: myobj.dosomething) contains a reference
+    Note that a bound method (ex: ``myobj.dosomething``) contains a reference
-    to 'self' (myobj in that case), so you will be keeping that object
+    to ``self`` (``myobj`` in that case), so you will be keeping that object
     alive too. Use ba.WeakCall if you want to pass a method to callback
     without keeping its object alive.
     """
@@ -248,6 +251,7 @@ class _Call:
                 str(self._args) + ' _keywds=' + str(self._keywds) + '>')
 
 
+# Hack: pdoc won't run this
 if TYPE_CHECKING:
     WeakCall = Call
     Call = Call

src/ballistica/python/class/python_class_input_device.cc

@@ -23,41 +23,41 @@ void PythonClassInputDevice::SetupType(PyTypeObject* obj) {
       "\n"
       "Attributes:\n"
       "\n"
-      "   allows_configuring: bool\n"
+      "   allows_configuring (bool):\n"
       "      Whether the input-device can be configured.\n"
       "\n"
-      "   has_meaningful_button_names: bool\n"
+      "   has_meaningful_button_names (bool):\n"
       "      Whether button names returned by this instance match labels\n"
       "      on the actual device. (Can be used to determine whether to show\n"
-      "      them in controls-overlays, etc.)\n"
+      "      them in controls-overlays, etc.).\n"
       "\n"
-      "   player: Optional[ba.SessionPlayer]\n"
+      "   player (Optional[ba.SessionPlayer]):\n"
       "      The player associated with this input device.\n"
       "\n"
-      "   client_id: int\n"
+      "   client_id (int):\n"
       "      The numeric client-id this device is associated with.\n"
       "      This is only meaningful for remote client inputs; for\n"
       "      all local devices this will be -1.\n"
       "\n"
-      "   name: str\n"
+      "   name (str):\n"
       "      The name of the device.\n"
       "\n"
-      "   unique_identifier: str\n"
+      "   unique_identifier (str):\n"
       "      A string that can be used to persistently identify the device,\n"
       "      even among other devices of the same type. Used for saving\n"
       "      prefs, etc.\n"
       "\n"
-      "   id: int\n"
+      "   id (int):\n"
       "      The unique numeric id of this device.\n"
       "\n"
-      "   instance_number: int\n"
+      "   instance_number (int):\n"
       "      The number of this device among devices of the same type.\n"
       "\n"
-      "   is_controller_app: bool\n"
+      "   is_controller_app (bool):\n"
       "      Whether this input-device represents a locally-connected\n"
       "      controller-app.\n"
       "\n"
-      "   is_remote_client: bool\n"
+      "   is_remote_client (bool):\n"
       "      Whether this input-device represents a remotely-connected\n"
       "      client.\n"
       "\n";

src/ballistica/python/class/python_class_material.cc

@@ -69,7 +69,7 @@ void PythonClassMaterial::SetupType(PyTypeObject* obj) {
       "\n"
       "Attributes:\n"
       "\n"
-      "    " ATTR_LABEL ": str\n"
+      "    " ATTR_LABEL " (str):\n"
       "        A label for the material; only used for debugging.\n";
   // clang-format on
 

tools/batools/docs.py

@@ -33,8 +33,8 @@ def parse_docs_attrs(attrs: list[AttributeInfo], docs: str) -> str:
         if line.strip() in ['Attributes:', 'Attrs:']:
             attr_line = i
             break
-    if attr_line is not None:
 
+    if attr_line is not None:
         # Docs is now everything *up to* this.
         docs = '\n'.join(docs_lines[:attr_line])
 
@@ -45,14 +45,16 @@ def parse_docs_attrs(attrs: list[AttributeInfo], docs: str) -> str:
 
             # A line with a single alphanumeric word preceding a colon
             # is a new attr.
-            splits = line.split(':')
+            splits = line.split(' ')
-            if (len(splits) in (1, 2) and splits[0]
+            if (len(splits) in (1, 2)
                     and splits[0].replace('_', '').isalnum()):
                 if cur_attr is not None:
                     attrs.append(cur_attr)
                 cur_attr = AttributeInfo(name=splits[0])
                 if len(splits) == 2:
-                    cur_attr.attr_type = splits[1]
+                    # Remove brackets and convert from
+                    # (type): to type.
+                    cur_attr.attr_type = splits[1][1:-2]
 
             # Any other line gets tacked onto the current attr.
             else:
@@ -84,6 +86,9 @@ def generate(projroot: str) -> None:
     outdirname = Path('build', 'docs_html').absolute()
 
     try:
+        pdoc.render.configure(docformat='google',
+                              search=True,
+                              show_source=True)
         pdoc.pdoc('ba', 'bastd', output_directory=outdirname)
     except Exception as exc:
         import traceback