Merge pull request #578 from Farama-Foundation/python-docs-update

Further improvments to the docs

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: `<current directory>`, `<current directory>/scenarios/`, `<ViZDoom library location>/scenarios/`.
 
-See also:
-- [Configuration files](../configurationFiles.md)
-
 
 ---
 ### `getMode`

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.

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.

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`
 

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",

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: ``<current directory>``, ``<current directory>/scenarios/``, ``<ViZDoom library location>/scenarios/``.
-
-See also:
-
-- `Configuration files <../configurationFiles/>`_)DOCSTRING";
+If the file relative path is given, it will be searched for in the following order: ``<current directory>``, ``<current directory>/scenarios/``, ``<ViZDoom library location>/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";