using dummy-module pdoc gen by default

This commit is contained in:
Eric 2023-06-13 10:58:53 -07:00
parent 648d2ce55f
commit 092ba5e433
No known key found for this signature in database
GPG Key ID: 89C93F0F8D6D5A98
9 changed files with 125 additions and 64 deletions

56
.efrocachemap generated
View File

@ -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/release/ballisticakit": "https://files.ballistica.net/cache/ba1/0e/99/b778ee89d825ad437afd5e985d74",
"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/release/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/89/89/670aab098a12f83e7e60db87c028",
"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/release/ballisticakit": "https://files.ballistica.net/cache/ba1/1a/50/eba589fe6c27bbecb717c644ae52",
"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/release/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/32/1c/e4e8cbff499975e12c73a43986a3",
"build/prefab/full/mac_arm64_gui/debug/ballisticakit": "https://files.ballistica.net/cache/ba1/5a/48/1823ce966086d9db6aeecd434fce",
"build/prefab/full/mac_arm64_gui/release/ballisticakit": "https://files.ballistica.net/cache/ba1/9f/9e/68acd514f01a55e750aaf9870136",
"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/release/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/3f/b0/c3301e6d30b7ef398bb53a6318c8",
"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/release/ballisticakit": "https://files.ballistica.net/cache/ba1/8a/72/269f9f0f1f2d0429866be5d76db5",
"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/release/dist/ballisticakit_headless": "https://files.ballistica.net/cache/ba1/e1/7a/2ca64e3b1ef1e4a83c565ee30185",
"build/prefab/full/windows_x86_gui/debug/BallisticaKit.exe": "https://files.ballistica.net/cache/ba1/9f/77/cdd3caf8b07452fa84a93ef5d54d",
"build/prefab/full/windows_x86_gui/release/BallisticaKit.exe": "https://files.ballistica.net/cache/ba1/50/35/2abd0ba2c01c51cac45ca25d154f",
"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/release/dist/BallisticaKitHeadless.exe": "https://files.ballistica.net/cache/ba1/59/c2/82922c6bb43000f60e146d89ffff",
"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/8e/ff/b4b55a4431332c9ca887a67fbf71",
"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/25/cd/1c19ea3f8e5f8d227484d6cb8287",
"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/74/50/e65355d1d6bf42b678deacceba13",
"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/cc/f1/1395af8d8f105a6f2f5a22102b29",
"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/72/47/f2f9f40029b9e75ee7a42caf866a",
"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/24/bf/9f3ac3969a6b296d200c75313f25",
"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/9c/7d/bcb6736c26110528022f0addf13d",
"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/05/20/2b4b3500b2eef7f25877bc24e134",
"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/9c/7e/4be7551c2f043f42f8e1a4cb84ae",
"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/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.pdb": "https://files.ballistica.net/cache/ba1/60/70/928f79ea56be618d2c2a8f041848",
"build/prefab/lib/windows/Debug_Win32/BallisticaKitHeadlessPlus.lib": "https://files.ballistica.net/cache/ba1/30/3b/ebb3771011b506c2162eac0cc70f",
"build/prefab/lib/windows/Debug_Win32/BallisticaKitHeadlessPlus.pdb": "https://files.ballistica.net/cache/ba1/9b/7f/226e61a4f0fab3d66415451441c1",
"build/prefab/lib/windows/Release_Win32/BallisticaKitGenericPlus.lib": "https://files.ballistica.net/cache/ba1/ac/ea/7af50be6464252224a4a9878dd9b",
"build/prefab/lib/windows/Release_Win32/BallisticaKitGenericPlus.pdb": "https://files.ballistica.net/cache/ba1/88/92/349325fffda0d6f6cedfc462b997",
"build/prefab/lib/windows/Release_Win32/BallisticaKitHeadlessPlus.lib": "https://files.ballistica.net/cache/ba1/13/a2/a0a0457431a0219f2b6c665bbe4f",
"build/prefab/lib/windows/Release_Win32/BallisticaKitHeadlessPlus.pdb": "https://files.ballistica.net/cache/ba1/70/e5/42300dcb5257494588f140d2a3d9",
"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/da/45/28272fe43705d29294c50712c773",
"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/27/ac/8013cdbf63f90c8ef836f10845bb",
"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/e3/ce/e147052489017b99049440cc9b55",
"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/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",

View File

@ -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>

View File

@ -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

View File

@ -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>

View File

@ -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.

View File

@ -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

View File

@ -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()

View File

@ -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 {

View File

@ -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.
apprun.python_command(
'import batools.docs; batools.docs._run_pdoc_in_engine()',
purpose='pdocs generation',
include_project_tools=True,
env=dict(os.environ, EFRO_SUPPRESS_SET_CANONICAL_MODULE_NAMES='1'),
)
else:
# Gen docs using dummy modules.
_run_pdoc_with_dummy_modules()
# Grab names from live objects so things don't break if names
# change.
pycmd = f'import {__name__}; {__name__}.{_run_pdoc.__name__}()'
apprun.python_command(
pycmd,
purpose='pdocs generation',
include_project_tools=True,
env=dict(os.environ, EFRO_SUPPRESS_SET_CANONICAL_MODULE_NAMES='1'),
)
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
just intact enough for us to spit out docs from. The upside is
that they have full typing information about arguments/etc. so our
docs will be more complete than if we talk to the live engine.
Dummy modules stand in for native engine modules, and should be just
intact enough for us to spit out docs from.
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:
"""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 '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.
"""
def _run_pdoc() -> None:
"""Do the actual docs generation with pdoc."""
import time
import pdoc