Merge pull request #549 from Farama-Foundation/docs-update

Update the docs, add named arguments to the pybind11 module

CMakeLists.txt

@@ -3,7 +3,7 @@ cmake_minimum_required(VERSION 3.4)
 # Project + versions
 #-----------------------------------------------------------------------------------------------------------------------
 
-project(ViZDoom VERSION 1.2.0)
+project(ViZDoom VERSION 1.2.1)
 set(ViZDoom_VERSION_STR ${ViZDoom_VERSION_MAJOR}.${ViZDoom_VERSION_MINOR}.${ViZDoom_VERSION_PATCH})
 set(ViZDoom_VERSION_ID ${ViZDoom_VERSION_MAJOR}${ViZDoom_VERSION_MINOR}${ViZDoom_VERSION_PATCH})
 

docs/README.md

@@ -3,3 +3,9 @@
 This directory contains the documentation for ViZDOOm.
 
 For more information about how to contribute to the documentation go to our [CONTRIBUTING.md](https://github.com/Farama-Foundation/Celshast/blob/main/CONTRIBUTING.md)
+
+If you edit the C++ documentation (inside `api_cpp`), you need to run to update other files:
+```
+python scripts/create_python_docs_from_cpp_docs.py
+python scripts/create_python_docstrings_from_cpp_docs.py
+```

docs/api_cpp/configurationFiles.md → docs/api/configurationFiles.md

@@ -19,7 +19,7 @@ A violation of any of these rules will result in ignoring **only** the line with
 ### Appending values
 Each list assignment (**KEY = { VALUES }**)clears values specified for this key before (in other configuration files or in the code). That is why the **append operator(*KEY += { VALUES })** is available. This way you can more easily combine multiple configuration files and tinker in code.
 
-### <a name="config_keys"></a> Supported configuration keys:
+### Supported configuration keys:
 * `audioBufferEnabled/audio_buffer_enabled`
 * `audioBufferSize/audio_buffer_size`
 * `audioSamplingRate/audio_samping_rate`
@@ -112,7 +112,6 @@ mode = PLAYER
 
 # Difficulty of gameplay ranging from 1 (baby) to 5 (nightmare)
 doom_skill = 5
-
 ```
 
 Other examples of configuration files can be found in [https://github.com/Farama-Foundation/ViZDoom/tree/master/scenarios](https://github.com/Farama-Foundation/ViZDoom/tree/master/scenarios)

docs/api/cpp.md

@@ -0,0 +1,18 @@
+# C++ API
+
+ViZDoom is implemented in C++ and can be used as a C++ library. The C++ API is one-to-one with the Python API. The only difference is the use of `camelCase` instead of `snake_case` for method names.
+
+ViZDoom can be built as a static or dynamic library. The header files are located in the `include` directory.
+See [examples/cpp](https://github.com/Farama-Foundation/ViZDoom/tree/master/examples/cpp) for examples, including CMake files for building.
+
+
+```{toctree}
+:hidden:
+:caption: C++ API
+
+cpp/doomGame
+cpp/gameState
+cpp/enums
+cpp/exceptions
+cpp/utils
+```

docs/api_cpp/doomGame.md → docs/api/cpp/doomGame.md

@@ -1,6 +1,6 @@
 # DoomGame
 
-DoomGame is the main object of the ViZDoom library, representing a single instance of the Doom game and providing the interface for a single agent/player to interact with the game. The object allows sending actions to the game, getting the game state, etc.
+DoomGame is the main object of the ViZDoom library, representing a single instance of the Doom game and providing the interface for a single agent/player to interact with the game. The object allows sending actions to the game, getting the game state, etc. The declarations of this class and its methods can be found in the `include/ViZDoomGame.h` header file.
 
 Here we document all the methods of the DoomGame class and their corresponding Python bindings implemented as pybind11 module.
 

docs/api_cpp/enums.md → docs/api/cpp/enums.md

@@ -1,5 +1,8 @@
 # Enums
 
+ViZDoom is using few types of enums as parameters for its functions. Below you can find the description of all of them.
+The declarations of all the enums can be found in the `include/ViZDoomTypes.h` header file.
+
 ## `Mode`
 
 Enum type that defines all supported modes.
@@ -178,11 +181,11 @@ Other from 1 to 60 (global int 1-60) can be accessed as USER1 - USER60 GameVaria
 
 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`](Utilities.md#doomFixedToDouble),
+- [`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),
 - [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).
 
@@ -271,3 +274,6 @@ Added in 1.1.9.
 - **SR_11025**
 - **SR_22050**
 - **SR_44100**
+
+See also:
+- [`DoomGame: setAudioSamplingRate`](./doomGame.md#setaudiosamplingrate),

docs/api_cpp/exceptions.md → docs/api/cpp/exceptions.md

@@ -1,6 +1,9 @@
 # Exceptions
 
 ViZDoom defines several exceptions that can be thrown by its API:
+Most of the exceptions contain more information in "what()" message.
+The declarations of all the enums can be found in the `include/ViZDoomExceptions.h` header file.
+
 
 * `FileDoesNotExistException` - means that file specified as part of a configuration does not exist.
 
@@ -13,5 +16,3 @@ ViZDoom defines several exceptions that can be thrown by its API:
 * `ViZDoomIsNotRunningException` - means that called method cannot be used when ViZDoom instance is not running.
 
 * `ViZDoomUnexpectedExitException` - means that ViZDoom's instance was closed/terminated/killed from the outside.
-
-Most of the exceptions contain more information in "what()" message.

docs/api_cpp/gameState.md → docs/api/cpp/gameState.md

@@ -1,6 +1,7 @@
 # GameState
 
 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.
 
 
 ## `GameState`
@@ -57,7 +58,10 @@ See also:
 - `double / float` **objectVelocityY / object_velocity_y**
 - `double / float` **objectVelocityZ / object_velocity_z**
 
-**objectId / object_id** - unique object ID, if both Labels and Objects information is enabled, this will be the same as **id** in corresponding**Object**.
+
+Description of the object in the labels buffer.
+
+**objectId / object_id** - unique object ID, if both Labels and Objects information is enabled, this will be the same as **id** in corresponding **Object**.
 
 **objectName / object_name** - ingame object name, many different objects can have the same name (e.g. Medikit, Clip, Zombie).
 
@@ -87,11 +91,12 @@ See also:
 - `double / float` **velocityY / velocity_y**
 - `double / float` **velocityZ / velocity_z**
 
+Description of the object present in the game world.
+
 **id** - unique object ID.
 
 **name** - ingame object name, many different objects can have the same name (e.g. Medikit, Clip, Zombie).
 
-Right now `Object` is only available to C++ and Python.
 Added in 1.1.8.
 
 See also:
@@ -109,13 +114,14 @@ See also:
 - `double / float` **y2**
 - `bool / bool` **isBlocking / is_blocking**
 
+Description of the line that is part of a sector definition.
+
 **x1**, **y1** - position of the line's first vertex.
 
 **x2**, **y2** - position of the line's second vertex.
 
 **isBlocking / is_blocking** - is true, if line is a wall that can't be passed.
 
-Right now `Line` is only available to C++ and Python.
 Added in 1.1.8.
 
 See also:
@@ -130,13 +136,14 @@ See also:
 - `double / float` **ceilingHeight / ceiling_height**
 - `std::vector<Label> / list` **lines**
 
+Description of the sector, part of the map with the same floor and ceiling height.
+
 **floorHeight / floor_height** - height of the sector's floor.
 
 **ceilingHeight / ceiling_height** - height of the sector's ceiling.
 
 **lines** - contains list of line segments, that forms sector.
 
-Right now `Sector` is only available to C++ and Python.
 Added in 1.1.8.
 
 See also:
@@ -146,11 +153,6 @@ See also:
 
 ---
 ## `ServerState`
-
-
-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.
-
-
 (`C++ type / Python type` **name**)
 
 - `unsigned int / int` **tic**
@@ -162,9 +164,9 @@ ServerState is the main object returned by [`DoomGame: getServerState`](./doomGa
 - `unsigned int[] / list` **playersLastActionTic / players_last_action_tic **
 - `unsigned int[] / list` **playersLastKillTic / players_last_kill_tic **
 
-Right now `ServerInfo` is only available to C++ and Python.
-Added in 1.1.6.
+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.
 
+Added in 1.1.6.
 
 See also:
 - [`DoomGame: getServerState`](./doomGame.md#getserverstate),

docs/api_cpp/utils.md → docs/api/cpp/utils.md

@@ -2,11 +2,11 @@
 
 Here we document the helpers functions that are not part of any object.
 They mostly help to deal with conversion of Doom's engine types.
+The declarations of all the enums can be found in the `include/ViZDoomUtils.h` header file.
 
 
 ## Time conversion functions
 
-
 ### `doomTicsToMs`
 
 | C++    | `double doomTicsToMs(double tics, unsigned int ticrate = 35)` |
@@ -56,8 +56,6 @@ Calculates the number of seconds that will pass during specified number of tics.
 
 ## Doom fixed point conversion functions
 
-
----
 ### `doomFixedToDouble`
 
 | C++    | `double doomFixedToDouble(int / double doomFixed)`      |
@@ -77,8 +75,6 @@ Python aliases (added in 1.1): `doom_fixed_to_float(doomFixed: int | float) -> f
 
 ## Button functions
 
-
----
 ### `isBinaryButton`
 
 | C++    | `bool isBinaryButton(Button button)`     |

docs/api/python.md

@@ -0,0 +1,19 @@
+# Python API
+
+ViZDoom provides Python bindings for the library. The Python API is one-to-one with the C++ API. The only difference is the use of `snake_case` instead of `camelCase` for method and argument names.
+
+There are many examples of how to use Python API in [examples/python](https://github.com/Farama-Foundation/ViZDoom/tree/master/examples/python) directory.
+
+
+```{toctree}
+:hidden:
+:caption: Python API
+
+python/doomGame
+python/gameState
+python/enums
+python/utils
+python/exceptions
+python/gymnasium
+python/gym
+```

docs/api_python/doomGame.md → docs/api/python/doomGame.md

@@ -2,9 +2,6 @@
 
 DoomGame is the main object of the ViZDoom library, representing a single instance of the Doom game and providing the interface for a single agent/player to interact with the game. The object allows sending actions to the game, getting the game state, etc.
 
-Here we document all the methods of the DoomGame class and their corresponding Python bindings implemented as pybind11 module.
-
-
 
 ```{eval-rst}
 .. autoclass:: vizdoom.DoomGame
@@ -100,6 +97,11 @@ Here we document all the methods of the DoomGame class and their corresponding P
 .. autofunction:: vizdoom.DoomGame.set_episode_start_time
 .. autofunction:: vizdoom.DoomGame.get_episode_timeout
 .. autofunction:: vizdoom.DoomGame.set_episode_timeout
+```
+
+## Output/rendering setting methods
+
+```{eval-rst}
 .. autofunction:: vizdoom.DoomGame.set_screen_resolution
 .. autofunction:: vizdoom.DoomGame.get_screen_format
 .. autofunction:: vizdoom.DoomGame.set_screen_format
@@ -141,3 +143,4 @@ Here we document all the methods of the DoomGame class and their corresponding P
 .. autofunction:: vizdoom.DoomGame.set_audio_sampling_rate
 .. autofunction:: vizdoom.DoomGame.get_audio_buffer_size
 .. autofunction:: vizdoom.DoomGame.set_audio_buffer_size
+```