From b2de92992ed509d8abdb4095c4d93c3b8de51e9b Mon Sep 17 00:00:00 2001 From: Marek Wydmuch Date: Sat, 16 Dec 2023 00:39:42 +0100 Subject: [PATCH] Further improvments to the docs --- docs/api/cpp/doomGame.md | 21 -------- docs/api/cpp/enums.md | 48 +++++++++---------- docs/api/cpp/gameState.md | 14 +++--- docs/api/cpp/utils.md | 6 +-- .../create_python_docstrings_from_cpp_docs.py | 1 - src/lib_python/ViZDoomMethodsDocstrings.h | 48 ++++--------------- 6 files changed, 44 insertions(+), 94 deletions(-) diff --git a/docs/api/cpp/doomGame.md b/docs/api/cpp/doomGame.md index 531bb4b9f..4e3866dd6 100644 --- a/docs/api/cpp/doomGame.md +++ b/docs/api/cpp/doomGame.md @@ -318,9 +318,6 @@ Has no effect when the game is running. Config key: `availableButtons`/`available_buttons` (list of values) -See also: -- [Configuration files: List of values](../configurationFiles.md#list-of-values) - --- ### `addAvailableButton` @@ -336,9 +333,6 @@ Has no effect when the game is running. Config key: `availableButtons`/`available_buttons` (list of values) -See also: -- [Configuration files: List of values](../configurationFiles.md#list-of-values) - --- ### `clearAvailableButtons` @@ -423,9 +417,6 @@ Has no effect when the game is running. Config key: `availableGameVariables`/`available_game_variables` (list of values) -See also: -- [Configuration files: List of values](../configurationFiles.md#list-of-values) - --- ### `addAvailableGameVariable` @@ -440,9 +431,6 @@ Has no effect when the game is running. Config key: `availableGameVariables`/`available_game_variables` (list of values) -See also: -- [Configuration files: List of values](../configurationFiles.md#list-of-values) - --- ### `clearAvailableGameVariables` @@ -455,9 +443,6 @@ Clears the list of available [`GameVariable`](./enums.md#gamevariable) s that ar Has no effect when the game is running. -See also: -- [Configuration files: List of values](../configurationFiles.md#list-of-values) - --- ### `getAvailableGameVariablesSize` @@ -469,9 +454,6 @@ See also: Returns the number of available [`GameVariable`](./enums.md#gamevariable). It corresponds to taking the size of the list returned by [`getAvailableGameVariables`](#getavailablegamevariables). -See also: -- [Configuration files: List of values](../configurationFiles.md#list-of-values) - --- ### `getGameVariable` @@ -634,9 +616,6 @@ false if the file contained errors. If the file relative path is given, it will be searched for in the following order: ``, `/scenarios/`, `/scenarios/`. -See also: -- [Configuration files](../configurationFiles.md) - --- ### `getMode` diff --git a/docs/api/cpp/enums.md b/docs/api/cpp/enums.md index 1aa90fa0b..31bc5a03c 100644 --- a/docs/api/cpp/enums.md +++ b/docs/api/cpp/enums.md @@ -23,10 +23,10 @@ In **ASYNC** modes the game progress with constant speed (default 35 tics per se All modes can be used in singleplayer and multiplayer. See also: -- [`DoomGame: getMode`](./doomGame.md#getmode), -- [`DoomGame: setMode`](./doomGame.md#setmode), -- [`DoomGame: getTicrate`](./doomGame.md#getticrate), -- [`DoomGame: setTicrate`](./doomGame.md#setticrate). +- [`DoomGame::getMode`](./doomGame.md#getmode), +- [`DoomGame::setMode`](./doomGame.md#setmode), +- [`DoomGame::getTicrate`](./doomGame.md#getticrate), +- [`DoomGame::setTicrate`](./doomGame.md#setticrate). --- @@ -57,8 +57,8 @@ In **GRAY8** and **DOOM_256_COLORS8** format **screenBuffer** and **automapBuffe **depthBuffer** and **lablesBuffer** always store single 8-bit values, so they always have [y, x] shape. See also: -- [`DoomGame: getScreenFormat`](./doomGame.md#getscreenformat), -- [`DoomGame: setScreenFormat`](./doomGame.md#setscreenformat), +- [`DoomGame::getScreenFormat`](./doomGame.md#getscreenformat), +- [`DoomGame::setScreenFormat`](./doomGame.md#setscreenformat), - [examples/python/buffers.py](https://github.com/Farama-Foundation/ViZDoom/tree/master/examples/python/buffers.py). @@ -105,9 +105,9 @@ Enum type that defines all supported resolutions - shapes of **screenBuffer**, * - **RES_1920X1080** (16:9) See also: -- [`DoomGame: setScreenResolution`](./doomGame.md#setscreenresolution), -- [`DoomGame: getScreenWidth`](./doomGame.md#getscreenwidth), -- [`DoomGame: getScreenHeight`](./doomGame.md#getscreenheight). +- [`DoomGame::setScreenResolution`](./doomGame.md#setscreenresolution), +- [`DoomGame::getScreenWidth`](./doomGame.md#getscreenwidth), +- [`DoomGame::getScreenHeight`](./doomGame.md#getscreenheight). --- @@ -121,7 +121,7 @@ Enum type that defines all **automapBuffer** modes. - **OBJECTS_WITH_SIZE** - In addition to the previous, all things are wrapped in a box showing their size. See also: -- [`DoomGame: setAutomapMode`](./doomGame.md#setautomapmode), +- [`DoomGame::setAutomapMode`](./doomGame.md#setautomapmode), - [examples/python/buffers.py](https://github.com/Farama-Foundation/ViZDoom/tree/master/examples/python/buffers.py). @@ -177,17 +177,17 @@ Enum type that defines all variables that can be obtained from the game. ACS global int variables can be accessed as USER GameVariables. global int 0 is reserved for reward and is always treated as Doom's fixed point numeral. -Other from 1 to 60 (global int 1-60) can be accessed as USER1 - USER60 GameVariables. -If you assign fixed point numeral to USER1 - USER60 GameVariables, +Other from 1 to 60 (global int 1-60) can be accessed as `USER1` - `USER60` GameVariables. +If you assign fixed point numeral to `USER1` - `USER60` GameVariables, you can convert them to floating point by using [`doomFixedToDouble`](utils.md#doomfixedtodouble) function. See also: - [ZDoom Wiki: ACS](http://zdoom.org/wiki/ACS), -- [`DoomGame: getAvailableGameVariables`](./doomGame.md#getavailablegamevariables), -- [`DoomGame: setAvailableGameVariables`](./doomGame.md#setavailablegamevariables), -- [`DoomGame: addAvailableGameVariable`](./doomGame.md#addavailablegamevariable), -- [`DoomGame: getGameVariable`](./doomGame.md#getgamevariable), -- [`Utilities: doomFixedToDouble`](utils.md#doomfixedtodouble), +- [`DoomGame::getAvailableGameVariables`](./doomGame.md#getavailablegamevariables), +- [`DoomGame::setAvailableGameVariables`](./doomGame.md#setavailablegamevariables), +- [`DoomGame::addAvailableGameVariable`](./doomGame.md#addavailablegamevariable), +- [`DoomGame::getGameVariable`](./doomGame.md#getgamevariable), +- [`doomFixedToDouble`](utils.md#doomfixedtodouble), - [examples/python/basic.py](https://github.com/Farama-Foundation/ViZDoom/tree/master/examples/python/basic.py), - [examples/python/shaping.py](https://github.com/Farama-Foundation/ViZDoom/tree/master/examples/python/shaping.py). @@ -245,7 +245,7 @@ Binary buttons have only 2 states "not pressed" if value 0 and "pressed" if valu Buttons whose value defines the speed of movement. A positive value indicates movement in the first specified direction and a negative value in the second direction. -For example: value 10 for MOVE_LEFT_RIGHT_DELTA means slow movement to the right and -100 means fast movement to the left. +For example: value 10 for `MOVE_LEFT_RIGHT_DELTA` means slow movement to the right and -100 means fast movement to the left. - **LOOK_UP_DOWN_DELTA** - **TURN_LEFT_RIGHT_DELTA** @@ -258,11 +258,11 @@ In case of **MOVE_FORWARD_BACKWARD_DELTA**, **MOVE_LEFT_RIGHT_DELTA**, **MOVE_UP See also: - [Doom Wiki: Map unit](https://doomwiki.org/wiki/Map_unit), -- [`DoomGame: getAvailableButtons`](./doomGame.md#getavailablebuttons), -- [`DoomGame: setAvailableButtons`](./doomGame.md#setavailablebuttons), -- [`DoomGame: addAvailableButton`](./doomGame.md#addavailablebutton), -- [`DoomGame: setButtonMaxValue`](./doomGame.md#setbuttonmaxvalue), -- [`DoomGame: getButtonMaxValue`](./doomGame.md#getbuttonmaxvalue), +- [`DoomGame::getAvailableButtons`](./doomGame.md#getavailablebuttons), +- [`DoomGame::setAvailableButtons`](./doomGame.md#setavailablebuttons), +- [`DoomGame::addAvailableButton`](./doomGame.md#addavailablebutton), +- [`DoomGame::setButtonMaxValue`](./doomGame.md#setbuttonmaxvalue), +- [`DoomGame::getButtonMaxValue`](./doomGame.md#getbuttonmaxvalue), - [examples/python/basic.py](https://github.com/Farama-Foundation/ViZDoom/tree/master/examples/python/basic.py), - [examples/python/delta_buttons.py](https://github.com/Farama-Foundation/ViZDoom/tree/master/examples/python/delta_buttons.py), - [GitHub issue: Angle changes by executing certain commands](https://github.com/Farama-Foundation/ViZDoom/issues/182). @@ -277,6 +277,6 @@ Enum type that defines all supported sampling rates for **audioBuffer** in **Sta - **SR_44100** See also: -- [`DoomGame: setAudioSamplingRate`](./doomGame.md#setaudiosamplingrate). +- [`DoomGame::setAudioSamplingRate`](./doomGame.md#setaudiosamplingrate). Note: added in 1.1.9. diff --git a/docs/api/cpp/gameState.md b/docs/api/cpp/gameState.md index 666ecdf63..08c2d0df4 100644 --- a/docs/api/cpp/gameState.md +++ b/docs/api/cpp/gameState.md @@ -1,6 +1,6 @@ # GameState -GameState is the main object returned by [`DoomGame: getState`](./doomGame.md#getstate) method. +GameState is the main object returned by [`DoomGame::getState`](./doomGame.md#getstate) method. The declarations of all the enums can be found in the `include/ViZDoomTypes.h` header file. @@ -21,7 +21,7 @@ The declarations of all the enums can be found in the `include/ViZDoomTypes.h` h **tic** - ingame time, 1 tic is 1/35 of second in the game world. Note: added in 1.1.1. See also: -- [`DoomGame: getState`](./doomGame.md#getstate), +- [`DoomGame::getState`](./doomGame.md#getstate), - [examples/python/basic.py](https://github.com/Farama-Foundation/ViZDoom/tree/master/examples/python/basic.py), - [examples/python/buffers.py](https://github.com/Farama-Foundation/ViZDoom/tree/master/examples/python/buffers.py). - [examples/python/audio_buffer.py](https://github.com/Farama-Foundation/ViZDoom/tree/master/examples/python/audio_buffer.py). @@ -71,7 +71,7 @@ Description of the object in the labels buffer. See also: -- [`DoomGame: setLabelsBufferEnabled`](./doomGame.md#setlabelsbufferenabled), +- [`DoomGame::setLabelsBufferEnabled`](./doomGame.md#setlabelsbufferenabled), - [examples/python/objects_and_sectors.py](https://github.com/Farama-Foundation/ViZDoom/tree/master/examples/python/labels_buffer.py). @@ -98,7 +98,7 @@ Description of the object present in the game world. **name** - ingame object name, many different objects can have the same name (e.g. Medikit, Clip, Zombie). See also: -- [`DoomGame: setObjectsInfoEnabled`](./doomGame.md#setsectorsinfoenabled), +- [`DoomGame::setObjectsInfoEnabled`](./doomGame.md#setsectorsinfoenabled), - [examples/python/objects_and_sectors.py](https://github.com/Farama-Foundation/ViZDoom/tree/master/examples/python/objects_and_sectors.py). Note: added in 1.1.8. @@ -145,7 +145,7 @@ Description of the sector, part of the map with the same floor and ceiling heigh **lines** - contains list of line segments, that forms sector. See also: -- [`DoomGame: setSectorsInfoEnabled`](./doomGame.md#setsectorsinfoenabled), +- [`DoomGame::setSectorsInfoEnabled`](./doomGame.md#setsectorsinfoenabled), - [examples/python/objects_and_sectors.py](https://github.com/Farama-Foundation/ViZDoom/tree/master/examples/python/objects_and_sectors.py). Note: added in 1.1.8. @@ -164,9 +164,9 @@ Note: added in 1.1.8. - `unsigned int[] / list` **playersLastActionTic / players_last_action_tic ** - `unsigned int[] / list` **playersLastKillTic / players_last_kill_tic ** -ServerState is the main object returned by [`DoomGame: getServerState`](./doomGame.md#getserverstate) method, and it purpose is to get more information about the state of the multi-player game. +ServerState is the main object returned by [`DoomGame::getServerState`](./doomGame.md#getserverstate) method, and it purpose is to get more information about the state of the multi-player game. See also: -- [`DoomGame: getServerState`](./doomGame.md#getserverstate), +- [`DoomGame::getServerState`](./doomGame.md#getserverstate), Note: added in 1.1.6. diff --git a/docs/api/cpp/utils.md b/docs/api/cpp/utils.md index 70dbaee60..3690aaba3 100644 --- a/docs/api/cpp/utils.md +++ b/docs/api/cpp/utils.md @@ -63,9 +63,9 @@ Note: added in 1.1.0 | Python | `doom_fixed_to_double(doom_fixed: int | float) -> float` | Converts fixed point numeral to a floating point value. -Doom's engine internally use fixed point numbers. -If you read them from `USER0` - `USER60` variables, -you should convert them to floating point numbers. +Doom engine internally use fixed point numbers. +If you assign fixed point numeral to `USER1` - `USER60` GameVariables, +you can convert them to floating point by using this function. Python alias (added in 1.1.0): `doom_fixed_to_float(doomFixed: int | float) -> float` diff --git a/scripts/create_python_docstrings_from_cpp_docs.py b/scripts/create_python_docstrings_from_cpp_docs.py index 98cc3032f..bcbf20afd 100755 --- a/scripts/create_python_docstrings_from_cpp_docs.py +++ b/scripts/create_python_docstrings_from_cpp_docs.py @@ -32,7 +32,6 @@ def camel_case_to_snake_case(text): r"\[([a-zA-Z/_\(\):\-\. \(\)]+)?\]\((.*)?\)", r"`\1 <\2>`_", ), # MD links -> RT links - (r"\.md([#a-zA-Z\-]*)>`_", r"/\1>`_"), # Fix links ending with .md ( r"^See also:.*$", "See also:\n", diff --git a/src/lib_python/ViZDoomMethodsDocstrings.h b/src/lib_python/ViZDoomMethodsDocstrings.h index 5dc6de6e6..615f062fe 100644 --- a/src/lib_python/ViZDoomMethodsDocstrings.h +++ b/src/lib_python/ViZDoomMethodsDocstrings.h @@ -135,22 +135,14 @@ that were added with :meth:`set_available_buttons` or/and :meth:`add_available_b Has no effect when the game is running. -Config key: ``availableButtons``/``available_buttons`` (list of values) - -See also: - -- `Configuration files: List of values <../configurationFiles/#list-of-values>`_)DOCSTRING"; +Config key: ``availableButtons``/``available_buttons`` (list of values))DOCSTRING"; const char *addAvailableButton = R"DOCSTRING(Adds :class:`.Button` type (e.g. ``TURN_LEFT``, ``MOVE_FORWARD``) to available buttons and sets the maximum allowed, absolute value for the specified button. If the given button has already been added, it will not be added again, but the maximum value will be overridden. Has no effect when the game is running. -Config key: ``availableButtons``/``available_buttons`` (list of values) - -See also: - -- `Configuration files: List of values <../configurationFiles/#list-of-values>`_)DOCSTRING"; +Config key: ``availableButtons``/``available_buttons`` (list of values))DOCSTRING"; const char *clearAvailableButtons = R"DOCSTRING(Clears all available :class:`.Button`s added so far. @@ -176,36 +168,20 @@ that were added with :meth:`set_available_game_variables` or/and :meth:`add_avai Has no effect when the game is running. -Config key: ``availableGameVariables``/``available_game_variables`` (list of values) - -See also: - -- `Configuration files: List of values <../configurationFiles/#list-of-values>`_)DOCSTRING"; +Config key: ``availableGameVariables``/``available_game_variables`` (list of values))DOCSTRING"; const char *addAvailableGameVariable = R"DOCSTRING(Adds the specified :class:`.GameVariable` to the list of available game variables (e.g. ``HEALTH``, ``AMMO1``, ``ATTACK_READY``) in the :class:`.GameState` returned by :meth:`get_state` method. Has no effect when the game is running. -Config key: ``availableGameVariables``/``available_game_variables`` (list of values) - -See also: - -- `Configuration files: List of values <../configurationFiles/#list-of-values>`_)DOCSTRING"; +Config key: ``availableGameVariables``/``available_game_variables`` (list of values))DOCSTRING"; const char *clearAvailableGameVariables = R"DOCSTRING(Clears the list of available :class:`.GameVariable` s that are included in the :class:`.GameState` returned by :meth:`get_state` method. -Has no effect when the game is running. - -See also: - -- `Configuration files: List of values <../configurationFiles/#list-of-values>`_)DOCSTRING"; +Has no effect when the game is running.)DOCSTRING"; const char *getAvailableGameVariablesSize = R"DOCSTRING(Returns the number of available :class:`.GameVariable`. -It corresponds to taking the size of the list returned by :meth:`get_available_game_variables`. - -See also: - -- `Configuration files: List of values <../configurationFiles/#list-of-values>`_)DOCSTRING"; +It corresponds to taking the size of the list returned by :meth:`get_available_game_variables`.)DOCSTRING"; const char *getGameVariable = R"DOCSTRING(Returns the current value of the specified :class:`.GameVariable` (``HEALTH``, ``AMMO1`` etc.). The specified game variable does not need to be among available game variables (included in the state). @@ -268,11 +244,7 @@ Overwriting does not involve resetting to default values. Thus only overlapping The method returns ``True`` if the whole configuration file was correctly read and applied, `False` if the file contained errors. -If the file relative path is given, it will be searched for in the following order: ````, ``/scenarios/``, ``/scenarios/``. - -See also: - -- `Configuration files <../configurationFiles/>`_)DOCSTRING"; +If the file relative path is given, it will be searched for in the following order: ````, ``/scenarios/``, ``/scenarios/``.)DOCSTRING"; const char *getMode = R"DOCSTRING(Returns the current :class:`.Mode` (``PLAYER``, ``SPECTATOR``, ``ASYNC_PLAYER``, ``ASYNC_SPECTATOR``).)DOCSTRING"; @@ -738,9 +710,9 @@ Note: added in 1.1.0)DOCSTRING"; Note: added in 1.1.0)DOCSTRING"; const char *doomFixedToDouble = R"DOCSTRING(Converts fixed point numeral to a floating point value. -Doom's engine internally use fixed point numbers. -If you read them from ``USER0`` - ``USER60`` variables, -you should convert them to floating point numbers.)DOCSTRING"; +Doom engine internally use fixed point numbers. +If you assign fixed point numeral to ``USER1`` - ``USER60`` GameVariables, +you can convert them to floating point by using this function.)DOCSTRING"; const char *isBinaryButton = R"DOCSTRING(Returns ``True`` if :class:`.Button` is binary button.)DOCSTRING";