Merge pull request #544 from Farama-Foundation/python_docstrings

Python docstrings

doc/DoomGame.md

@@ -530,7 +530,7 @@ See also:
 ## <a name="vars"></a> GameVariables methods
 
 ---
-### <a name="getAvailableGameVariable"></a> `getAvailableGameVariable`
+### <a name="getAvailableGameVariables"></a> `getAvailableGameVariables`
 
 | C++    | `std::vector<GameVariable> getAvailableGameVariables()` |
 | :--    | :--                                                     |
@@ -1542,11 +1542,11 @@ See also:
 
 
 ---
-### <a name="getAudioSampliongRate"></a> `getAudioSamplingRate`
+### <a name="getAudioSamplingRate"></a> `getAudioSamplingRate`
 
-| C++    | `SamplingRate getAudioSamplingRate()`    |
+| C++    | `int getAudioSamplingRate()`    |
 | :--    | :--                                      |
-| Python | `SamplingRate get_audio_sampling_rate()` |
+| Python | `int get_audio_sampling_rate()` |
 
 Added in 1.1.9
 

scripts/create_python_docstrings_from_docs.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+
+import re
+
+
+FILES_TO_PARSE = [
+    {"filepath": "doc/DoomGame.md", "namespace": "DoomGamePython"},
+    {"filepath": "doc/Utilities.md"},
+]
+OUTPUT_FILE = "src/lib_python/ViZDoomDocstrings.h"
+RAW_STRING_ESCAPE_SEQ = "DOCSTRING"
+FUNCTION_HEADER_REGEX = r"^### *<a *name=\"([a-zA-Z]+)\"><\/a> *`([a-zA-Z]+)` *$"
+LINES_TO_IGNORE_REGEXES = [
+    r"---",  # Lines
+    r"^\|.+\|$",  # Tables
+    r"^See also:.*$",  # See also
+    r"- \[.*\]\(.*\)",  # List of links starting with -
+    r"\* \[.*\]\(.*\)",  # List of links starting with *
+    r"^Added in .*$",  # Added in annotations
+    r"^Changed in .*$",  # Changed in annotations
+    r"^Deprecated since .*$",  # Deprecated since annotations
+    r"^Removed in .*$",  # Removed in annotations
+    r"^Config key: .*$",  # Config annotations
+]
+
+
+if __name__ == "__main__":
+    with open(OUTPUT_FILE, "w") as output_file:
+        output_file.write(
+            """
+/*
+    This file is autogenerated by scripts/create_python_docstrings_from_docs.py
+    Do not edit it manually. Edit the Markdown files instead and regenerate it.
+*/
+
+#ifndef __VIZDOOM_DOCSTRINGS_H__
+#define __VIZDOOM_DOCSTRINGS_H__
+
+namespace vizdoom {{
+namespace docstrings {{
+
+"""
+        )
+
+        for file in FILES_TO_PARSE:
+            if "namespace" in file:
+                output_file.write(f"namespace {file['namespace']} {{\n\n")
+
+            with open(file["filepath"]) as f:
+                lines = f.readlines()
+
+            started = False
+            next_docstring = ""
+            for line in lines:
+                # If lines match pattern, extract the function name and arguments
+                match = re.match(FUNCTION_HEADER_REGEX, line)
+                if match:
+                    if started:
+                        next_docstring = next_docstring.strip()
+                        next_docstring += f'){RAW_STRING_ESCAPE_SEQ}";\n\n'
+                        output_file.write(next_docstring)
+
+                    next_docstring = ""
+                    function_name = match.group(1)
+                    output_file.write(
+                        f'    const char *{function_name} = R"{RAW_STRING_ESCAPE_SEQ}('
+                    )
+                    started = True
+
+                elif started:
+                    # Filter out some lines
+                    if not any(re.match(r, line) for r in LINES_TO_IGNORE_REGEXES):
+                        next_docstring += line
+
+            if started:
+                output_file.write(f'){RAW_STRING_ESCAPE_SEQ}";\n\n')
+
+            if "namespace" in file:
+                output_file.write(f"}} // namespace {file['namespace']}\n\n")
+
+        output_file.write(
+            """
+} // namespace docstrings
+} // namespace vizdoom
+#endif
+"""
+        )

src/lib_python/CMakeLists.txt

@@ -42,6 +42,7 @@ configure_file(
 )
 
 set(VIZDOOM_PYTHON_SOURCES
+    ${VIZDOOM_PYTHON_SRC_DIR}/ViZDoomDocstrings.h
     ${VIZDOOM_PYTHON_SRC_DIR}/ViZDoomGamePython.h
     ${VIZDOOM_PYTHON_SRC_DIR}/ViZDoomGamePython.cpp
     ${VIZDOOM_PYTHON_SRC_DIR}/ViZDoomPythonModule.cpp)