using dummy-module pdoc gen by default

.efrocachemap

@@ -4072,26 +4072,26 @@
   "build/assets/workspace/ninjafightplug.py": "https://files.ballistica.net/cache/ba1/18/4b/787a9267e17be3c49966072581a5",
   "build/assets/workspace/onslaughtplug.py": "https://files.ballistica.net/cache/ba1/20/f6/4ce9bc3c1f3732f6adf8237fbe9b",
   "build/assets/workspace/runaroundplug.py": "https://files.ballistica.net/cache/ba1/a5/30/9058181df0b1255bf6950cbc7813",
-  "build/prefab/full/linux_arm64_gui/debug/ballisticakit": "https://files.ballistica.net/cache/ba1/62/cd/d08e770b38acf623b5b1bb127e5d",
+  "build/prefab/full/linux_arm64_gui/debug/ballisticakit": "https://files.ballistica.net/cache/ba1/a9/1a/d3954587d948c34aaa93c416164b",
-  "build/prefab/full/linux_arm64_gui/release/ballisticakit": "https://files.ballistica.net/cache/ba1/0e/99/b778ee89d825ad437afd5e985d74",
+  "build/prefab/full/linux_arm64_gui/release/ballisticakit": "https://files.ballistica.net/cache/ba1/8e/ff/b4b55a4431332c9ca887a67fbf71",
-  "build/prefab/full/linux_arm64_server/debug/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/37/19/e96634dcf5cf0b82d43f1452c310",
+  "build/prefab/full/linux_arm64_server/debug/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/f3/08/98de2f087a4f7cb1d9a1034a3220",
-  "build/prefab/full/linux_arm64_server/release/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/89/89/670aab098a12f83e7e60db87c028",
+  "build/prefab/full/linux_arm64_server/release/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/25/cd/1c19ea3f8e5f8d227484d6cb8287",
-  "build/prefab/full/linux_x86_64_gui/debug/ballisticakit": "https://files.ballistica.net/cache/ba1/89/29/7a6e474273dff5d5155c8dc76780",
+  "build/prefab/full/linux_x86_64_gui/debug/ballisticakit": "https://files.ballistica.net/cache/ba1/10/13/fe2b90d207c702a982bf96e44c3b",
-  "build/prefab/full/linux_x86_64_gui/release/ballisticakit": "https://files.ballistica.net/cache/ba1/1a/50/eba589fe6c27bbecb717c644ae52",
+  "build/prefab/full/linux_x86_64_gui/release/ballisticakit": "https://files.ballistica.net/cache/ba1/74/50/e65355d1d6bf42b678deacceba13",
-  "build/prefab/full/linux_x86_64_server/debug/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/ae/6d/3a40474aa8072a124a0487267e23",
+  "build/prefab/full/linux_x86_64_server/debug/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/03/08/c3346fc329d34f19f2e3543a734e",
-  "build/prefab/full/linux_x86_64_server/release/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/32/1c/e4e8cbff499975e12c73a43986a3",
+  "build/prefab/full/linux_x86_64_server/release/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/cc/f1/1395af8d8f105a6f2f5a22102b29",
-  "build/prefab/full/mac_arm64_gui/debug/ballisticakit": "https://files.ballistica.net/cache/ba1/5a/48/1823ce966086d9db6aeecd434fce",
+  "build/prefab/full/mac_arm64_gui/debug/ballisticakit": "https://files.ballistica.net/cache/ba1/95/bb/5514281e755e860acbcd612443e3",
-  "build/prefab/full/mac_arm64_gui/release/ballisticakit": "https://files.ballistica.net/cache/ba1/9f/9e/68acd514f01a55e750aaf9870136",
+  "build/prefab/full/mac_arm64_gui/release/ballisticakit": "https://files.ballistica.net/cache/ba1/72/47/f2f9f40029b9e75ee7a42caf866a",
-  "build/prefab/full/mac_arm64_server/debug/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/ec/cd/6883d013c07be8c7116601b8480b",
+  "build/prefab/full/mac_arm64_server/debug/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/08/93/edeb433317a962d11485ec41d911",
-  "build/prefab/full/mac_arm64_server/release/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/3f/b0/c3301e6d30b7ef398bb53a6318c8",
+  "build/prefab/full/mac_arm64_server/release/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/24/bf/9f3ac3969a6b296d200c75313f25",
-  "build/prefab/full/mac_x86_64_gui/debug/ballisticakit": "https://files.ballistica.net/cache/ba1/d4/4b/6b2bf7e37b24c8279c697e98ca12",
+  "build/prefab/full/mac_x86_64_gui/debug/ballisticakit": "https://files.ballistica.net/cache/ba1/bd/3d/a35a7bf2a1e83db9c7f6486cffa6",
-  "build/prefab/full/mac_x86_64_gui/release/ballisticakit": "https://files.ballistica.net/cache/ba1/8a/72/269f9f0f1f2d0429866be5d76db5",
+  "build/prefab/full/mac_x86_64_gui/release/ballisticakit": "https://files.ballistica.net/cache/ba1/9c/7d/bcb6736c26110528022f0addf13d",
-  "build/prefab/full/mac_x86_64_server/debug/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/22/fa/43eb0ed9388165d5ddac79fc9c8d",
+  "build/prefab/full/mac_x86_64_server/debug/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/00/81/7ff15082671a039cd2a469994476",
-  "build/prefab/full/mac_x86_64_server/release/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/e1/7a/2ca64e3b1ef1e4a83c565ee30185",
+  "build/prefab/full/mac_x86_64_server/release/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/05/20/2b4b3500b2eef7f25877bc24e134",
-  "build/prefab/full/windows_x86_gui/debug/BallisticaKit.exe": "https://files.ballistica.net/cache/ba1/9f/77/cdd3caf8b07452fa84a93ef5d54d",
+  "build/prefab/full/windows_x86_gui/debug/BallisticaKit.exe": "https://files.ballistica.net/cache/ba1/51/25/8f981fc4590e9ccc119d334f2767",
-  "build/prefab/full/windows_x86_gui/release/BallisticaKit.exe": "https://files.ballistica.net/cache/ba1/50/35/2abd0ba2c01c51cac45ca25d154f",
+  "build/prefab/full/windows_x86_gui/release/BallisticaKit.exe": "https://files.ballistica.net/cache/ba1/9c/7e/4be7551c2f043f42f8e1a4cb84ae",
-  "build/prefab/full/windows_x86_server/debug/dist/BallisticaKitHeadless.exe": "https://files.ballistica.net/cache/ba1/65/b9/4e1ebf0753fad9e3adec9a598efc",
+  "build/prefab/full/windows_x86_server/debug/dist/BallisticaKitHeadless.exe": "https://files.ballistica.net/cache/ba1/93/8e/24faa33217f66ddbf44f501f3fc6",
-  "build/prefab/full/windows_x86_server/release/dist/BallisticaKitHeadless.exe": "https://files.ballistica.net/cache/ba1/59/c2/82922c6bb43000f60e146d89ffff",
+  "build/prefab/full/windows_x86_server/release/dist/BallisticaKitHeadless.exe": "https://files.ballistica.net/cache/ba1/40/86/0f92a45a76ff540174c2306eeafe",
   "build/prefab/lib/linux_arm64_gui/debug/libballistica_plus.a": "https://files.ballistica.net/cache/ba1/29/dc/e5b08aae2dbe3222082aaa1e90e7",
   "build/prefab/lib/linux_arm64_gui/release/libballistica_plus.a": "https://files.ballistica.net/cache/ba1/ce/bb/5796a83ce9d1c9cf58e08f3ff351",
   "build/prefab/lib/linux_arm64_server/debug/libballistica_plus.a": "https://files.ballistica.net/cache/ba1/31/65/014221e46f7974f40aa84c8922dc",
@@ -4108,14 +4108,14 @@
   "build/prefab/lib/mac_x86_64_gui/release/libballistica_plus.a": "https://files.ballistica.net/cache/ba1/14/4b/68a0ece3c1f191183b695cf45a4d",
   "build/prefab/lib/mac_x86_64_server/debug/libballistica_plus.a": "https://files.ballistica.net/cache/ba1/1f/3f/d899a46cc0dc8bc4f1b38f9318a5",
   "build/prefab/lib/mac_x86_64_server/release/libballistica_plus.a": "https://files.ballistica.net/cache/ba1/de/99/95fdcb3f614a7b83ada148bca38d",
-  "build/prefab/lib/windows/Debug_Win32/BallisticaKitGenericPlus.lib": "https://files.ballistica.net/cache/ba1/4f/6b/ebfab34748dfdeda9a9336c3d208",
+  "build/prefab/lib/windows/Debug_Win32/BallisticaKitGenericPlus.lib": "https://files.ballistica.net/cache/ba1/81/52/74280b0576ea7a471fb77efea1e4",
-  "build/prefab/lib/windows/Debug_Win32/BallisticaKitGenericPlus.pdb": "https://files.ballistica.net/cache/ba1/60/70/928f79ea56be618d2c2a8f041848",
+  "build/prefab/lib/windows/Debug_Win32/BallisticaKitGenericPlus.pdb": "https://files.ballistica.net/cache/ba1/da/45/28272fe43705d29294c50712c773",
-  "build/prefab/lib/windows/Debug_Win32/BallisticaKitHeadlessPlus.lib": "https://files.ballistica.net/cache/ba1/30/3b/ebb3771011b506c2162eac0cc70f",
+  "build/prefab/lib/windows/Debug_Win32/BallisticaKitHeadlessPlus.lib": "https://files.ballistica.net/cache/ba1/63/ed/2d14fa909698d6f1237fda2bbbf0",
-  "build/prefab/lib/windows/Debug_Win32/BallisticaKitHeadlessPlus.pdb": "https://files.ballistica.net/cache/ba1/9b/7f/226e61a4f0fab3d66415451441c1",
+  "build/prefab/lib/windows/Debug_Win32/BallisticaKitHeadlessPlus.pdb": "https://files.ballistica.net/cache/ba1/27/ac/8013cdbf63f90c8ef836f10845bb",
-  "build/prefab/lib/windows/Release_Win32/BallisticaKitGenericPlus.lib": "https://files.ballistica.net/cache/ba1/ac/ea/7af50be6464252224a4a9878dd9b",
+  "build/prefab/lib/windows/Release_Win32/BallisticaKitGenericPlus.lib": "https://files.ballistica.net/cache/ba1/ce/60/daf6d760463bd2c18d80c1bdb2b4",
-  "build/prefab/lib/windows/Release_Win32/BallisticaKitGenericPlus.pdb": "https://files.ballistica.net/cache/ba1/88/92/349325fffda0d6f6cedfc462b997",
+  "build/prefab/lib/windows/Release_Win32/BallisticaKitGenericPlus.pdb": "https://files.ballistica.net/cache/ba1/e3/ce/e147052489017b99049440cc9b55",
-  "build/prefab/lib/windows/Release_Win32/BallisticaKitHeadlessPlus.lib": "https://files.ballistica.net/cache/ba1/13/a2/a0a0457431a0219f2b6c665bbe4f",
+  "build/prefab/lib/windows/Release_Win32/BallisticaKitHeadlessPlus.lib": "https://files.ballistica.net/cache/ba1/54/2e/6c035774dbdcf3398ce9cf575fe5",
-  "build/prefab/lib/windows/Release_Win32/BallisticaKitHeadlessPlus.pdb": "https://files.ballistica.net/cache/ba1/70/e5/42300dcb5257494588f140d2a3d9",
+  "build/prefab/lib/windows/Release_Win32/BallisticaKitHeadlessPlus.pdb": "https://files.ballistica.net/cache/ba1/02/90/3fb7f942b44d41cc8b62f300783c",
   "src/assets/ba_data/python/babase/_mgen/__init__.py": "https://files.ballistica.net/cache/ba1/52/c6/c11130af7b10d6c0321add5518fa",
   "src/assets/ba_data/python/babase/_mgen/enums.py": "https://files.ballistica.net/cache/ba1/38/c3/1dedd5e74f2508efc5974c8815a1",
   "src/ballistica/base/mgen/pyembed/binding_base.inc": "https://files.ballistica.net/cache/ba1/ea/6a/6a4721b144e5e297b542d2a0eea2",

.idea/dictionaries/ericf.xml

@@ -1804,6 +1804,7 @@
       <w>mtvos</w>
       <w>mtype</w>
       <w>mtypenames</w>
+      <w>muckery</w>
       <w>mult</w>
       <w>multibytecodec</w>
       <w>multikillcount</w>

CHANGELOG.md

@@ -1,4 +1,4 @@
-### 1.7.20 (build 21094, api 8, 2023-06-13)
+### 1.7.20 (build 21095, api 8, 2023-06-13)
 
 - This seems like a good time for a `refactoring` release in anticipation of
   changes coming in 1.8. Basically this means that a lot of things will be

ballisticakit-cmake/.idea/dictionaries/ericf.xml

@@ -1041,6 +1041,7 @@
       <w>msgtypes</w>
       <w>msgtypevar</w>
       <w>mtypenames</w>
+      <w>muckery</w>
       <w>mult</w>
       <w>multing</w>
       <w>multipass</w>

src/assets/ba_data/python/babase/_app.py

@@ -3,6 +3,7 @@
 """Functionality related to the high level state of the app."""
 from __future__ import annotations
 
+import os
 from enum import Enum
 import logging
 from typing import TYPE_CHECKING
@@ -230,6 +231,9 @@ class App:
         the single shared instance.
         """
 
+        if os.environ.get('BA_RUNNING_WITH_DUMMY_MODULES') == '1':
+            return
+
         self.state = self.State.INITIAL
 
         self._subsystems: list[AppSubsystem] = []
@@ -295,6 +299,9 @@ class App:
     def postinit(self) -> None:
         """Called after we are inited and assigned to babase.app."""
 
+        if os.environ.get('BA_RUNNING_WITH_DUMMY_MODULES') == '1':
+            return
+
         # NOTE: the reason we need a postinit here is that
         # some of this stuff accesses babase.app and that doesn't
         # exist yet as of our __init__() call.

src/assets/ba_data/python/baenv.py

@@ -28,7 +28,7 @@ if TYPE_CHECKING:
 
 # Build number and version of the ballistica binary we expect to be
 # using.
-TARGET_BALLISTICA_BUILD = 21094
+TARGET_BALLISTICA_BUILD = 21095
 TARGET_BALLISTICA_VERSION = '1.7.20'
 
 _g_env_config: EnvConfig | None = None

src/assets/ba_data/python/bauiv1lib/store/browser.py

@@ -4,6 +4,7 @@
 # pylint: disable=too-many-lines
 from __future__ import annotations
 
+import os
 import time
 import copy
 import math
@@ -1408,5 +1409,8 @@ def _check_merch_availability_in_bg_thread() -> None:
 # Slight hack; start checking merch availability in the bg
 # (but only if it looks like we're part of a running app; don't want to
 # do this during docs generation/etc.)
-if bui.app.state is not bui.app.State.INITIAL:
+if (
+    os.environ.get('BA_RUNNING_WITH_DUMMY_MODULES') != '1'
+    and bui.app.state is not bui.app.State.INITIAL
+):
     Thread(target=_check_merch_availability_in_bg_thread, daemon=True).start()

src/ballistica/shared/ballistica.cc

@@ -39,7 +39,7 @@ auto main(int argc, char** argv) -> int {
 namespace ballistica {
 
 // These are set automatically via script; don't modify them here.
-const int kEngineBuildNumber = 21094;
+const int kEngineBuildNumber = 21095;
 const char* kEngineVersion = "1.7.20";
 
 auto MonolithicMain(const core::CoreConfig& core_config) -> int {

tools/batools/docs.py

@@ -5,6 +5,8 @@
 from __future__ import annotations
 
 import os
+import sys
+import subprocess
 from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING
@@ -24,6 +26,9 @@ class AttributeInfo:
     docs: str | None = None
 
 
+_g_genned_pdoc_with_dummy_modules = False  # pylint: disable=invalid-name
+
+
 def parse_docs_attrs(attrs: list[AttributeInfo], docs: str) -> str:
     """Given a docs str, parses attribute descriptions contained within."""
     docs_lines = docs.splitlines()
@@ -75,10 +80,30 @@ def parse_docs_attrs(attrs: list[AttributeInfo], docs: str) -> str:
 
 def generate_pdoc(projroot: str) -> None:
     """Generate a set of pdoc documentation."""
-    from batools import apprun
-
     del projroot  # Unused.
 
+    if bool(False):
+        _run_pdoc_in_engine()
+    else:
+        _run_pdoc_with_dummy_modules()
+
+
+def _run_pdoc_in_engine() -> None:
+    """Generate docs from within the running engine.
+
+    The upside of this way is we have all built-in native modules
+    available. The downside is that we don't have typing information
+    for those modules aside from what's embedded in their docstrings
+    (which is not parsed by pdoc). So we get lots of ugly 'unknown'
+    arg types in docs/etc.
+
+    The ideal solution might be to start writing .pyi files for
+    our native modules to provide their type information instead
+    of or in addition to our dummy-module approach. Just need to
+    see how that works with our pipeline.
+    """
+    from batools import apprun
+
     # Assemble and launch an app and do our docs generation from there.
     # Note: we set EFRO_SUPPRESS_SET_CANONICAL_MODULE_NAMES because pdoc
     # spits out lots of "UserWarning: cannot determine where FOO was
@@ -86,44 +111,67 @@ def generate_pdoc(projroot: str) -> None:
     # it makes in the output though. Basically the canonical names stuff
     # makes things like bascenev1._actor.Actor show up as
     # bascenev1.Actor instead.
-    if bool(True):
+
-        # Gen docs from the engine.
+    # Grab names from live objects so things don't break if names
-        apprun.python_command(
+    # change.
-            'import batools.docs; batools.docs._run_pdoc_in_engine()',
+    pycmd = f'import {__name__}; {__name__}.{_run_pdoc.__name__}()'
-            purpose='pdocs generation',
+    apprun.python_command(
-            include_project_tools=True,
+        pycmd,
-            env=dict(os.environ, EFRO_SUPPRESS_SET_CANONICAL_MODULE_NAMES='1'),
+        purpose='pdocs generation',
-        )
+        include_project_tools=True,
-    else:
+        env=dict(os.environ, EFRO_SUPPRESS_SET_CANONICAL_MODULE_NAMES='1'),
-        # Gen docs using dummy modules.
+    )
-        _run_pdoc_with_dummy_modules()
 
 
 def _run_pdoc_with_dummy_modules() -> None:
     """Generate docs outside of the engine using our dummy modules.
 
-    Dummy modules stand in for native engine modules, and should be
+    Dummy modules stand in for native engine modules, and should be just
-    just intact enough for us to spit out docs from. The upside is
+    intact enough for us to spit out docs from.
-    that they have full typing information about arguments/etc. so our
+
-    docs will be more complete than if we talk to the live engine.
+    The upside is that dummy modules have full typing information about
+    arguments/etc. so some docs will be more complete than if we talk to
+    the live engine.
+
+    The downside is that we have to hack the engine a bit to be able to
+    spin itself up this way and there may be bits missing that would
+    otherwise not be when running in a live engine.
     """
-    raise RuntimeError('UNDER CONSTRUCTION')
+
+    # Not that this is likely to happen, but we muck with sys paths and
+    # whatnot here so let's make sure we only do this once.
+    global _g_genned_pdoc_with_dummy_modules  # pylint: disable=global-statement
+    if _g_genned_pdoc_with_dummy_modules:
+        raise RuntimeError(
+            'Can only run this once; it mucks with the environment.'
+        )
+    _g_genned_pdoc_with_dummy_modules = True
+
+    # Make sure dummy-modules are up to date and make them discoverable
+    # to Python.
+    subprocess.run(['make', 'dummymodules'], check=True)
+    sys.path.append('build/dummymodules')
+
+    # Turn off canonical module name muckery (see longer note above).
+    os.environ['EFRO_SUPPRESS_SET_CANONICAL_MODULE_NAMES'] = '1'
+
+    # Short circuits a few things in our Python code allowing this to
+    # work.
+    os.environ['BA_RUNNING_WITH_DUMMY_MODULES'] = '1'
+
+    # Use raw sources for our other stuff.
+    sys.path.append('src/assets/ba_data/python')
+
+    # We're using raw source dirs in this case, and we don't want Python
+    # dumping .pyc files there as it causes various small headaches with
+    # build pipeline stuff.
+    sys.dont_write_bytecode = True
+
+    _run_pdoc()
 
 
-def _run_pdoc_in_engine() -> None:
+def _run_pdoc() -> None:
-    """Generate docs from within the running engine.
+    """Do the actual docs generation with pdoc."""
-
-    The upside of this way is we have all built-in native modules
-    available. The downside is that we don't have typing information for
-    those modules aside from what's embedded in their docstrings (which
-    is not parsed by pdoc). So we get lots of 'unknown' arg types in
-    docs/etc.
-
-    The ideal solution might be to start writing .pyi files for our
-    native modules to provide their type information instead of or in
-    addition to our dummy-module approach. Just need to see how that
-    works with our pipeline.
-    """
     import time
 
     import pdoc