From e09b49249f7faed27892871c59b921bb759af0d8 Mon Sep 17 00:00:00 2001 From: Eric Date: Mon, 12 Jun 2023 16:59:02 -0700 Subject: [PATCH] updated pdoc generation for the new state of the world --- .efrocachemap | 32 ++++---- .idea/dictionaries/ericf.xml | 2 + Makefile | 10 ++- .../.idea/dictionaries/ericf.xml | 2 + src/assets/ba_data/python/bascenev1/_actor.py | 4 +- .../ba_data/python/bauiv1lib/store/browser.py | 6 +- tools/batools/apprun.py | 25 ++++-- tools/batools/docs.py | 79 ++++++++----------- 8 files changed, 90 insertions(+), 70 deletions(-) diff --git a/.efrocachemap b/.efrocachemap index 10b7b69c..521302a1 100644 --- a/.efrocachemap +++ b/.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/release/BallisticaKit.exe": "https://files.ballistica.net/cache/ba1/f6/d6/4cba97ea982b68ccca077f3da940", - "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/release/dist/BallisticaKitHeadless.exe": "https://files.ballistica.net/cache/ba1/c0/7c/b3e1038df89ad796bf48112292a3", + "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/e4/e1/ccae5b1d66d0699902061aaaf32f", + "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/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.pdb": "https://files.ballistica.net/cache/ba1/16/7f/fbca5f52a5c7a2d30cff06edc6ac", - "build/prefab/lib/windows/Debug_Win32/BallisticaKitHeadlessPlus.lib": "https://files.ballistica.net/cache/ba1/0e/e6/b1f8b6cad401ebe410b201bb1520", - "build/prefab/lib/windows/Debug_Win32/BallisticaKitHeadlessPlus.pdb": "https://files.ballistica.net/cache/ba1/c9/17/d230ae94c0c4fcd2f4d37f65e303", - "build/prefab/lib/windows/Release_Win32/BallisticaKitGenericPlus.lib": "https://files.ballistica.net/cache/ba1/81/43/c98ad0db3e97698a8f9bd0b9bb4f", - "build/prefab/lib/windows/Release_Win32/BallisticaKitGenericPlus.pdb": "https://files.ballistica.net/cache/ba1/2b/02/601e10b59d453dd6caf42779be2a", - "build/prefab/lib/windows/Release_Win32/BallisticaKitHeadlessPlus.lib": "https://files.ballistica.net/cache/ba1/a5/8c/54ecc3d3ffee609cbb5099462b76", - "build/prefab/lib/windows/Release_Win32/BallisticaKitHeadlessPlus.pdb": "https://files.ballistica.net/cache/ba1/5a/94/333dd02759d5f8f3319b68c0cf39", + "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/93/c2/a78cfd84b3af9ac3d038639103db", + "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/b2/32/d3d1f4f49c0df51248b5dc4c2e2a", + "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/e9/03/e5e89fbafabee00cb27249908bdd", + "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/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", diff --git a/.idea/dictionaries/ericf.xml b/.idea/dictionaries/ericf.xml index 6ecadfcc..9fe6b5e7 100644 --- a/.idea/dictionaries/ericf.xml +++ b/.idea/dictionaries/ericf.xml @@ -127,6 +127,7 @@ appname appnameupper appnow + apprun appspot appstate appstore @@ -2323,6 +2324,7 @@ pyobjc pyoffs pypaths + pysitedir pysources pytest pythondevmode diff --git a/Makefile b/Makefile index f81e248d..6d0a8cc7 100644 --- a/Makefile +++ b/Makefile @@ -159,8 +159,14 @@ dummymodules-clean: rm -f $(LAZYBUILDDIR)/dummymodules rm -rf build/dummymodules -# Generate docs. -docs: assets-cmake +# Generate all docs. +# +# 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. diff --git a/ballisticakit-cmake/.idea/dictionaries/ericf.xml b/ballisticakit-cmake/.idea/dictionaries/ericf.xml index bc7b5fd5..ecb1e0c4 100644 --- a/ballisticakit-cmake/.idea/dictionaries/ericf.xml +++ b/ballisticakit-cmake/.idea/dictionaries/ericf.xml @@ -85,6 +85,7 @@ appname appnameupper appnow + apprun appspot appstate appsubsystem @@ -1333,6 +1334,7 @@ pymodulenames pyobj pyobjs + pysitedir pythondevmode pythonenumsmodule pytype diff --git a/src/assets/ba_data/python/bascenev1/_actor.py b/src/assets/ba_data/python/bascenev1/_actor.py index fc22c1bc..178a901d 100644 --- a/src/assets/ba_data/python/bascenev1/_actor.py +++ b/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 - and don't care how many Python references to them exist. + bascenev1.Node, which is always explicitly created and destroyed + 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 diff --git a/src/assets/ba_data/python/bauiv1lib/store/browser.py b/src/assets/ba_data/python/bauiv1lib/store/browser.py index d989027c..0a727107 100644 --- a/src/assets/ba_data/python/bauiv1lib/store/browser.py +++ b/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() diff --git a/tools/batools/apprun.py b/tools/batools/apprun.py index b249933e..da012835 100755 --- a/tools/batools/apprun.py +++ b/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: - """Run a cmd with a built bin and PYTHONPATH set to its scripts dir.""" +def python_command( + 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) diff --git a/tools/batools/docs.py b/tools/batools/docs.py index 43b7a68c..5ee4fc13 100755 --- a/tools/batools/docs.py +++ b/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: - """Main entry point.""" - from batools.version import get_current_version +def _run_pdoc_in_engine() -> None: + import time + import pdoc + import babase - # Since we're operating on source dirs, suppress .pyc generation. - # (__pycache__ dirs accumulating in source dirs causes some subtle - # headaches) - sys.dont_write_bytecode = True + starttime = time.monotonic() - # Make sure we're running from the dir above this script. - os.chdir(projroot) + # Tell pdoc to go through all the modules we've got in + # 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 = ( - Path(projroot) / 'assets' / 'src' / 'pdoc' / 'templates' - ).absolute() - pythondir = ( - Path(projroot) / 'assets' / 'src' / 'ba_data' / 'python' - ).absolute() - outdirname = (Path(projroot) / 'build' / 'docs_html').absolute() - sys.path.append(str(pythondir)) + templatesdir = Path('src/assets/pdoc/templates') + assert templatesdir.is_dir() - 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: - os.environ['BA_DOCS_GENERATION'] = '1' - 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}') + duration = time.monotonic() - starttime + print(f'{Clr.GRN}Generated pdoc documentation in {duration:.1f}s.{Clr.RST}')