updated pdoc generation for the new state of the world

.efrocachemap

@@ -4080,18 +4080,18 @@
   "build/prefab/full/linux_x86_64_gui/release/ballisticakit": "https://files.ballistica.net/cache/ba1/5b/c6/92d0ba8ca612e475b72260a19e98",
   "build/prefab/full/linux_x86_64_server/debug/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/b7/bd/b8ac02a5e68a1069e8f95e694878",
   "build/prefab/full/linux_x86_64_server/release/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/7d/79/e42dfe45c7b2c1a50d10b4e09efe",
-  "build/prefab/full/mac_arm64_gui/debug/ballisticakit": "https://files.ballistica.net/cache/ba1/c4/61/751004a93730969c0db2dfb3af78",
+  "build/prefab/full/mac_arm64_gui/debug/ballisticakit": "https://files.ballistica.net/cache/ba1/fb/3c/888c3beeb09977558c1e912f6aff",
   "build/prefab/full/mac_arm64_gui/release/ballisticakit": "https://files.ballistica.net/cache/ba1/ad/ce/473c60a90b856145b0cf587cda4c",
-  "build/prefab/full/mac_arm64_server/debug/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/72/ab/8989c81e50c77eaa2beb509ca862",
+  "build/prefab/full/mac_arm64_server/debug/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/af/36/c3449a1ad727cbd4cf42bd11c5df",
   "build/prefab/full/mac_arm64_server/release/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/6a/8a/b5db085b0e7c302592339e71bb7e",
-  "build/prefab/full/mac_x86_64_gui/debug/ballisticakit": "https://files.ballistica.net/cache/ba1/d1/50/54e3e478047c2ff2af05989afb32",
+  "build/prefab/full/mac_x86_64_gui/debug/ballisticakit": "https://files.ballistica.net/cache/ba1/8e/fd/6e2afbdb66384c749013723c707f",
   "build/prefab/full/mac_x86_64_gui/release/ballisticakit": "https://files.ballistica.net/cache/ba1/ca/80/8f44943b05b5fb9cb4e1c1c5763d",
-  "build/prefab/full/mac_x86_64_server/debug/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/51/7e/bb43ebba603a9ec64ddfb7fd9543",
+  "build/prefab/full/mac_x86_64_server/debug/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/a4/d9/c985d945323974b3ffe68c369920",
   "build/prefab/full/mac_x86_64_server/release/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/48/e9/cbc79d892e48a419fb06201b664b",
-  "build/prefab/full/windows_x86_gui/debug/BallisticaKit.exe": "https://files.ballistica.net/cache/ba1/88/47/bfd87fc3bd48d1da2fb32e3c70ee",
+  "build/prefab/full/windows_x86_gui/debug/BallisticaKit.exe": "https://files.ballistica.net/cache/ba1/8b/db/1ad894a5955845728effcfb90cb4",
-  "build/prefab/full/windows_x86_gui/release/BallisticaKit.exe": "https://files.ballistica.net/cache/ba1/f6/d6/4cba97ea982b68ccca077f3da940",
+  "build/prefab/full/windows_x86_gui/release/BallisticaKit.exe": "https://files.ballistica.net/cache/ba1/e4/e1/ccae5b1d66d0699902061aaaf32f",
-  "build/prefab/full/windows_x86_server/debug/dist/BallisticaKitHeadless.exe": "https://files.ballistica.net/cache/ba1/83/e1/da3c4daaf0161eb9f4f90695faf3",
+  "build/prefab/full/windows_x86_server/debug/dist/BallisticaKitHeadless.exe": "https://files.ballistica.net/cache/ba1/58/a6/bb1fff8654879f42c4c0a047ec18",
-  "build/prefab/full/windows_x86_server/release/dist/BallisticaKitHeadless.exe": "https://files.ballistica.net/cache/ba1/c0/7c/b3e1038df89ad796bf48112292a3",
+  "build/prefab/full/windows_x86_server/release/dist/BallisticaKitHeadless.exe": "https://files.ballistica.net/cache/ba1/08/9d/9280655e38fa6ac9102cd59d989c",
   "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/12/2b/3688e05860461e26714da59d7cb0",
+  "build/prefab/lib/windows/Debug_Win32/BallisticaKitGenericPlus.lib": "https://files.ballistica.net/cache/ba1/a3/3b/2e04778c0cbbe2d0d14895c307ad",
-  "build/prefab/lib/windows/Debug_Win32/BallisticaKitGenericPlus.pdb": "https://files.ballistica.net/cache/ba1/16/7f/fbca5f52a5c7a2d30cff06edc6ac",
+  "build/prefab/lib/windows/Debug_Win32/BallisticaKitGenericPlus.pdb": "https://files.ballistica.net/cache/ba1/93/c2/a78cfd84b3af9ac3d038639103db",
-  "build/prefab/lib/windows/Debug_Win32/BallisticaKitHeadlessPlus.lib": "https://files.ballistica.net/cache/ba1/0e/e6/b1f8b6cad401ebe410b201bb1520",
+  "build/prefab/lib/windows/Debug_Win32/BallisticaKitHeadlessPlus.lib": "https://files.ballistica.net/cache/ba1/50/d5/0607b905a484d13fca8684c63da3",
-  "build/prefab/lib/windows/Debug_Win32/BallisticaKitHeadlessPlus.pdb": "https://files.ballistica.net/cache/ba1/c9/17/d230ae94c0c4fcd2f4d37f65e303",
+  "build/prefab/lib/windows/Debug_Win32/BallisticaKitHeadlessPlus.pdb": "https://files.ballistica.net/cache/ba1/b2/32/d3d1f4f49c0df51248b5dc4c2e2a",
-  "build/prefab/lib/windows/Release_Win32/BallisticaKitGenericPlus.lib": "https://files.ballistica.net/cache/ba1/81/43/c98ad0db3e97698a8f9bd0b9bb4f",
+  "build/prefab/lib/windows/Release_Win32/BallisticaKitGenericPlus.lib": "https://files.ballistica.net/cache/ba1/00/dc/84886617ad467015a285f514f9b1",
-  "build/prefab/lib/windows/Release_Win32/BallisticaKitGenericPlus.pdb": "https://files.ballistica.net/cache/ba1/2b/02/601e10b59d453dd6caf42779be2a",
+  "build/prefab/lib/windows/Release_Win32/BallisticaKitGenericPlus.pdb": "https://files.ballistica.net/cache/ba1/e9/03/e5e89fbafabee00cb27249908bdd",
-  "build/prefab/lib/windows/Release_Win32/BallisticaKitHeadlessPlus.lib": "https://files.ballistica.net/cache/ba1/a5/8c/54ecc3d3ffee609cbb5099462b76",
+  "build/prefab/lib/windows/Release_Win32/BallisticaKitHeadlessPlus.lib": "https://files.ballistica.net/cache/ba1/cc/a6/5a2e6205973b51ac02346c145c47",
-  "build/prefab/lib/windows/Release_Win32/BallisticaKitHeadlessPlus.pdb": "https://files.ballistica.net/cache/ba1/5a/94/333dd02759d5f8f3319b68c0cf39",
+  "build/prefab/lib/windows/Release_Win32/BallisticaKitHeadlessPlus.pdb": "https://files.ballistica.net/cache/ba1/9a/cb/09c3d55a75692af03a0ec9f68afa",
   "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

@@ -127,6 +127,7 @@
       <w>appname</w>
       <w>appnameupper</w>
       <w>appnow</w>
+      <w>apprun</w>
       <w>appspot</w>
       <w>appstate</w>
       <w>appstore</w>
@@ -2323,6 +2324,7 @@
       <w>pyobjc</w>
       <w>pyoffs</w>
       <w>pypaths</w>
+      <w>pysitedir</w>
       <w>pysources</w>
       <w>pytest</w>
       <w>pythondevmode</w>

Makefile

@@ -159,8 +159,14 @@ dummymodules-clean:
 	rm -f $(LAZYBUILDDIR)/dummymodules
 	rm -rf build/dummymodules
 
-# Generate docs.
+# Generate all docs.
-docs: assets-cmake
+#
+# IMPORTANT: Docs generation targets may themselves run builds, so they should
+#  be run alone serially.
+docs:
+	$(MAKE) docs-pdoc
+
+docs-pdoc:
 	@tools/pcommand gen_docs_pdoc
 
 # Tell make which of these targets don't represent files.

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

@@ -85,6 +85,7 @@
       <w>appname</w>
       <w>appnameupper</w>
       <w>appnow</w>
+      <w>apprun</w>
       <w>appspot</w>
       <w>appstate</w>
       <w>appsubsystem</w>
@@ -1333,6 +1334,7 @@
       <w>pymodulenames</w>
       <w>pyobj</w>
       <w>pyobjs</w>
+      <w>pysitedir</w>
       <w>pythondevmode</w>
       <w>pythonenumsmodule</w>
       <w>pytype</w>

src/assets/ba_data/python/bascenev1/_actor.py

@@ -53,8 +53,8 @@ class Actor:
     ... self.flag = None
 
     This is in contrast to the behavior of the more low level
-    bascenev1.Nodes, which are always explicitly created and destroyed
+    bascenev1.Node, which is always explicitly created and destroyed
-    and don't care how many Python references to them exist.
+    and doesn't care how many Python references to it exist.
 
     Note, however, that you can use the bascenev1.Actor.autoretain() method
     if you want an Actor to stick around until explicitly killed

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

@@ -1405,4 +1405,8 @@ def _check_merch_availability_in_bg_thread() -> None:
         time.sleep(1.1934)  # A bit randomized to avoid aliasing.
 
 
-Thread(target=_check_merch_availability_in_bg_thread, daemon=True).start()
+# 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:
+    Thread(target=_check_merch_availability_in_bg_thread, daemon=True).start()

tools/batools/apprun.py

@@ -40,17 +40,33 @@ def acquire_binary_for_python_command(purpose: str) -> str:
     return acquire_binary(assets=True, purpose=purpose)
 
 
-def python_command(cmd: str, purpose: str) -> None:
+def python_command(
-    """Run a cmd with a built bin and PYTHONPATH set to its scripts dir."""
+    cmd: str, purpose: str, include_project_tools: bool = False
+) -> None:
+    """Run a cmd with a built bin and PYTHONPATH set to its scripts."""
 
     binpath = acquire_binary_for_python_command(purpose=purpose)
     bindir = os.path.dirname(binpath)
 
+    # We'll set both the app python dir and its site-python-dir. This
+    # should let us get at most engine stuff. We could also just use
+    # baenv to set up app paths, but that might be overkill and could
+    # unintentionally bring in stuff like local mods.
+    pydir = f'{bindir}/ba_data/python'
+    assert os.path.isdir(pydir)
+    pysitedir = f'{bindir}/ba_data/python-site-packages'
+    assert os.path.isdir(pysitedir)
+
+    # Make our tools dir available if asked.
+    tools_path_extra = ':tools' if include_project_tools else ''
+
     cmdargs = [binpath, '--command', cmd]
-    print(f'Running command: {cmdargs}...')
+    print(f"apprun: Running with Python command: '{cmdargs}'...", flush=True)
     subprocess.run(
         cmdargs,
-        env=dict(os.environ, PYTHONPATH=f'{bindir}/ba_data/python'),
+        env=dict(
+            os.environ, PYTHONPATH=f'{pydir}:{pysitedir}{tools_path_extra}'
+        ),
         check=True,
     )
 
@@ -160,4 +176,3 @@ def acquire_binary(assets: bool, purpose: str) -> str:
             f"Binary not found at expected path '{binary_path}'."
         )
     return binary_path
-    # subprocess.run(['make', 'scripts-cmake'], cwd='src/assets', check=True)

tools/batools/docs.py

@@ -4,13 +4,11 @@
 
 from __future__ import annotations
 
-import sys
 import os
 from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING
 
-from efro.error import CleanError
 from efro.terminal import Clr
 
 if TYPE_CHECKING:
@@ -76,54 +74,47 @@ def parse_docs_attrs(attrs: list[AttributeInfo], docs: str) -> str:
 
 
 def generate_pdoc(projroot: str) -> None:
-    """Main entry point."""
+    """Generate a set of pdoc documentation."""
+    from batools import apprun
+
     del projroot  # Unused.
-    print('WOULD DO DOCS')
+
+    # Assemble and launch an app and do our docs generation from there.
+    apprun.python_command(
+        'import batools.docs; batools.docs._run_pdoc_in_engine()',
+        purpose='pdocs generation',
+        include_project_tools=True,
+    )
 
 
-def do_generate_pdoc(projroot: str) -> None:
+def _run_pdoc_in_engine() -> None:
-    """Main entry point."""
+    import time
-    from batools.version import get_current_version
+
     import pdoc
+    import babase
 
-    # Since we're operating on source dirs, suppress .pyc generation.
+    starttime = time.monotonic()
-    # (__pycache__ dirs accumulating in source dirs causes some subtle
-    # headaches)
-    sys.dont_write_bytecode = True
 
-    # Make sure we're running from the dir above this script.
+    # Tell pdoc to go through all the modules we've got in
-    os.chdir(projroot)
+    # ba_data/python.
+    modulenames = sorted(
+        n.removesuffix('.py')
+        for n in os.listdir('src/assets/ba_data/python')
+        if not n.startswith('.')
+    )
+    assert modulenames
 
-    templatesdir = (
+    templatesdir = Path('src/assets/pdoc/templates')
-        Path(projroot) / 'assets' / 'src' / 'pdoc' / 'templates'
+    assert templatesdir.is_dir()
-    ).absolute()
-    pythondir = (
-        Path(projroot) / 'assets' / 'src' / 'ba_data' / 'python'
-    ).absolute()
-    outdirname = (Path(projroot) / 'build' / 'docs_html').absolute()
-    sys.path.append(str(pythondir))
 
-    version, build_number = get_current_version()
+    pdoc.render.env.globals['ba_version'] = babase.app.version
+    pdoc.render.env.globals['ba_build'] = babase.app.build_number
+    pdoc.render.configure(
+        search=True,
+        show_source=True,
+        template_directory=Path('src/assets/pdoc/templates'),
+    )
+    pdoc.pdoc(*modulenames, output_directory=Path('build/docs_pdoc'))
 
-    try:
+    duration = time.monotonic() - starttime
-        os.environ['BA_DOCS_GENERATION'] = '1'
+    print(f'{Clr.GRN}Generated pdoc documentation in {duration:.1f}s.{Clr.RST}')
-        pdoc.render.env.globals['ba_version'] = version
-        pdoc.render.env.globals['ba_build'] = build_number
-        pdoc.render.configure(
-            search=True, show_source=True, template_directory=templatesdir
-        )
-        pdoc.pdoc(
-            'babase',
-            'bascenev1lib',
-            'baclassic',
-            'bascenev1',
-            'bauiv1',
-            output_directory=outdirname,
-        )
-    except Exception as exc:
-        import traceback
-
-        traceback.print_exc()
-        raise CleanError('Docs generation failed') from exc
-
-    print(f'{Clr.GRN}Docs generation complete.{Clr.RST}')