From 7673e01b9b710b59fed0b6a38debf27a8b05e3ec Mon Sep 17 00:00:00 2001 From: Roman Trapeznikov Date: Fri, 11 Feb 2022 11:51:00 +0300 Subject: [PATCH] workaround with docs --- assets/src/ba_data/python/._ba_sources_hash | 2 +- assets/src/ba_data/python/_ba.py | 35 ++++-------- assets/src/ba_data/python/ba/_general.py | 56 ++++++++++--------- .../python/class/python_class_input_device.cc | 22 ++++---- .../python/class/python_class_material.cc | 2 +- tools/batools/docs.py | 13 +++-- 6 files changed, 64 insertions(+), 66 deletions(-) diff --git a/assets/src/ba_data/python/._ba_sources_hash b/assets/src/ba_data/python/._ba_sources_hash index e00d6c53..29666224 100644 --- a/assets/src/ba_data/python/._ba_sources_hash +++ b/assets/src/ba_data/python/._ba_sources_hash @@ -1 +1 @@ -142084453862763162635228312125641718455 \ No newline at end of file +175217515325031448193730963697929841246 \ No newline at end of file diff --git a/assets/src/ba_data/python/_ba.py b/assets/src/ba_data/python/_ba.py index f67d9196..af61f73e 100644 --- a/assets/src/ba_data/python/_ba.py +++ b/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 diff --git a/assets/src/ba_data/python/ba/_general.py b/assets/src/ba_data/python/ba/_general.py index e919138a..a025c9f0 100644 --- a/assets/src/ba_data/python/ba/_general.py +++ b/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 - # bar() method 5 seconds later; it will be kept alive even though - # we overwrite its variable with None because the bound method - # we pass as a timer callback (foo.bar) strong-references it - foo = FooClass() - ba.timer(5.0, foo.bar) - foo = None + Examples: + EXAMPLE A: this code will create a FooClass instance and call its + bar() method 5 seconds later; it will be kept alive even though + we overwrite its variable with None because the bound method + we pass as a timer callback (foo.bar) strong-references it + >>> foo = FooClass() + ... ba.timer(5.0, foo.bar) + ... foo = None - # 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 - # fires - foo = FooClass() - ba.timer(5.0, ba.WeakCall(foo.bar)) - foo = None + 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 + fires + >>> foo = FooClass() + ... ba.timer(5.0, ba.WeakCall(foo.bar)) + ... foo = None - Note: additional args and keywords you provide to the WeakCall() - constructor are stored as regular strong-references; you'll need - to wrap them in weakrefs manually if desired. + Note: additional args and keywords you provide to the WeakCall() + constructor are stored as regular strong-references; you'll need + 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 - # keyword args: - myweakcall = ba.WeakCall(myobj.dostuff, argval1, namedarg=argval2) - - # Now we have a single callable to run that whole mess. - # The same as calling myobj.dostuff(argval1, namedarg=argval2) - # (provided my_obj still exists; this will do nothing otherwise) - myweakcall() + Examples: + Example: wrap a method call with some positional and + keyword args: + >>> myweakcall = ba.WeakCall(myobj.dostuff, argval1, + ... namedarg=argval2) + ... # Now we have a single callable to run that whole mess. + ... # The same as calling myobj.dostuff(argval1, namedarg=argval2) + ... # (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 - to 'self' (myobj in that case), so you will be keeping that object + Note that a bound method (ex: ``myobj.dosomething``) contains a reference + 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 diff --git a/src/ballistica/python/class/python_class_input_device.cc b/src/ballistica/python/class/python_class_input_device.cc index de70685d..c6840e7c 100644 --- a/src/ballistica/python/class/python_class_input_device.cc +++ b/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"; diff --git a/src/ballistica/python/class/python_class_material.cc b/src/ballistica/python/class/python_class_material.cc index fb6717e1..b5175919 100644 --- a/src/ballistica/python/class/python_class_material.cc +++ b/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 diff --git a/tools/batools/docs.py b/tools/batools/docs.py index c45b23af..08dcfa2d 100755 --- a/tools/batools/docs.py +++ b/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(':') - if (len(splits) in (1, 2) and splits[0] + splits = line.split(' ') + 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