docs

Author: JaskRendix

.github/workflows/build.yml

@@ -2,7 +2,7 @@ name: Tuxemon
 on:
   push:
     branches:
-    - development # only pushes on development. So the release variable will be set correctly
+      - development # only pushes on development. So the release variable will be set correctly
   pull_request:
   page_build:
   workflow_dispatch:
@@ -13,24 +13,25 @@ env:
 
 jobs:
   appdata_validation:
-    uses: ./.github/workflows/appdata_validation.yml 
+    uses: ./.github/workflows/appdata_validation.yml
 
 
   flatpak:
     uses: ./.github/workflows/flatpak.yml 
     with:
       IS_RELEASE: ${{ github.event_name == 'push' && github.ref_type == 'tag' && startswith(github.ref_name, 'v') }}
 
-
   build_installer_windows:
-    uses: ./.github/workflows/installer_windows.yml 
-
+    uses: ./.github/workflows/installer_windows.yml
 
   python-app:
-    uses: ./.github/workflows/python-app.yml 
+    uses: ./.github/workflows/python-app.yml
+
+  docs:
+    uses: ./.github/workflows/docs.yml
 
   publish:
-    needs: [flatpak, build_installer_windows]
+    needs: [flatpak, build_installer_windows, docs]
     runs-on: ubuntu-latest # does not matter which
     # a prerelase is created when pushing to master
     # a release is created when a tag will be set

.github/workflows/docs.yml

@@ -0,0 +1,33 @@
+name: Docs Build
+
+on:
+  push:
+    branches:
+      - '**'
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  docs:
+    name: Docs Build Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+          
+      - name: Install documentation dependencies and project
+        run: |
+          python -m pip install --upgrade pip
+          pip install sphinx sphinx-rtd-theme sphinx-autodoc-typehints
+          pip install .
+          
+      - name: Build Sphinx Documentation
+        run: |
+          sphinx-build -W -b html docs/ docs/_build

.readthedocs.yaml

@@ -12,4 +12,11 @@ sphinx:
 python:
     version: 3.10
     install:
-    - requirements: docs/requirements.txt
+    - requirements:
+        - sphinx
+        - sphinx-rtd-theme
+        - sphinx-autodoc-typehints
+        - sphinx.ext.napoleon
+    
+    - method: pip
+      path: .

docs/conf.py

@@ -4,92 +4,101 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-# -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
+# -- Path setup for importing project paths ------------------------------------
+#
+# The documentation must be able to import the main project package (tuxemon)
+# for extensions like autodoc and apidoc to work correctly.
 #
-import os
 import sys
-sys.path.append(os.path.abspath("./ext"))
-sys.path.insert(0, os.path.abspath('../'))
+from pathlib import Path
+from typing import Any
 
+CONF_DIR = Path(__file__).parent.resolve()
+PROJECT_ROOT = CONF_DIR.parent
+
+sys.path.insert(0, str(PROJECT_ROOT))
+sys.path.append(str(CONF_DIR / "ext"))
+sys.path.append(str(Path(__file__).parent.resolve() / "ext"))
 
 # -- Project information -----------------------------------------------------
-from typing import Any
 
-project = 'Tuxemon'
-copyright = '2015-2025, William Edwards'
-author = 'William Edwards'
+project = "Tuxemon"
+copyright = "2015-2025, William Edwards"
+author = "William Edwards"
 
 # The full version, including alpha/beta/rc tags
-release = 'alpha'
+# You could potentially get a dynamic version from your project here
+release = "alpha"
 
 
 # -- General configuration ---------------------------------------------------
 
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
+# Add any Sphinx extension module names here, as strings.
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.todo',
-    'sphinx.ext.viewcode',
-    'sphinx.ext.githubpages',
-    'sphinx.ext.napoleon',
-    'script_documenter',
+    "sphinx.ext.autodoc",
+    "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.githubpages",
+    "sphinx.ext.napoleon",
+    "script_documenter",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "autogen"]
 
 
-# -- Options for HTML output ----------------------------------------------
+# -- Options for HTML output -------------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
-html_theme = 'sphinx_rtd_theme'
+# The theme to use for HTML and HTML Help pages.
+html_theme = "sphinx_rtd_theme"
 
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# Add any paths that contain custom static files (such as style sheets) here.
+html_static_path = ["_static"]
 
+
+# -- Options for Autodoc and Napoleon ----------------------------------------
+
+# Tell Autodoc how to display type hints
 autodoc_typehints = "description"
 
+# Disable NumPy docstring parsing if you primarily use Google-style docstrings
 napoleon_numpy_docstring = False
 
+# Define your custom Napoleon sections
 napoleon_custom_sections = [
     "Script usage",
-    ("Script parameters", "params_style")
+    ("Script parameters", "params_style"),
 ]
 
 
-# Apidoc call to generate automatic reference docs. Taken from
-# https://github.com/readthedocs/readthedocs.org/issues/1139#issuecomment-398083449
+# -- Apidoc Automation -------------------------------------------------------
+
+
 def run_apidoc(_: Any) -> None:
+    """
+    Automatically runs sphinx-apidoc before the Sphinx build process begins.
+    This generates API reference files for all your project's modules.
+    """
     ignore_paths: list[str] = []
 
     argv = [
-        "-f",
-        "-e",
-        "-M",
-        "-o",
-        "autogen",
-        ".."
+        "-f",  # Force overwrite output files
+        "-e",  # Put documentation for each module on its own page
+        "-M",  # Look for module files instead of package files
+        "-o",  # Output directory
+        "autogen",  # Name of the directory to store the generated files
+        str(PROJECT_ROOT),  # Use the repo root so apidoc scans everything
     ] + ignore_paths
 
-    # Sphinx 1.7+
     from sphinx.ext import apidoc
+
     apidoc.main(argv)
 
 
 def setup(app: Any) -> None:
-    app.connect('builder-inited', run_apidoc)
+    """Connect the run_apidoc function to the 'builder-inited' Sphinx event."""
+    app.connect("builder-inited", run_apidoc)

tuxemon/event/actions/dojo_method.py

@@ -31,15 +31,21 @@ class DojoMethodAction(EventAction):
     Represents an event action for the monks in the Dojo (Spyder).
 
     Script Usage:
-        .. code-block::
 
-            dojo_method <variable_name>,<option>
+        .. code-block:: text
+
+        dojo_method <variable_name>,<option>
 
     Script Parameters:
-        variable_name: The name of the variable where the monster ID will be stored.
-        option: The action to perform. Can be either:
+
+        variable_name:
+            The name of the variable where the monster ID will be stored.
+
+        option:
+            The action to perform. Can be either:
+
             - "technique": Learn any move the monster hasn't acquired from its base
-                moveset, without restrictions based on level or evolution stage.
+            moveset, without restrictions based on level or evolution stage.
             - "monster": Devolve the monster.
     """
 

tuxemon/event/actions/info.py

@@ -19,23 +19,31 @@
 class InfoAction(EventAction):
     """
     Records monster's attribute values inside a game variable.
-    It allows to record the monster's owner attribute values too.
+    It allows recording the monster's owner attribute values too.
 
     Script usage:
-        .. code-block::
 
-            info <variable>,<attribute>
+        .. code-block:: text
+
+           info <variable>,<attribute>
 
     Script parameters:
-        variable: Name of the variable where to store the monster id.
-        attribute: The attribute to check (level, speed, etc.)
-
-    eg. "info name_variable,level"
-    -> if the monster is lv 4, then it'll create a variable called:
-        "info_level:4"
-    eg. "info name_variable,owner_steps"
-    -> if the owner walked 69 steps, then it'll create a variable called:
-        "info_owner_steps:69"
+
+        variable:
+            Name of the variable where to store the monster id.
+
+        attribute:
+            The attribute to check (level, speed, etc.)
+
+    Examples:
+
+        "info name_variable,level"
+        -> if the monster is lv 4, then it'll create a variable called:
+           "info_level:4"
+
+        "info name_variable,owner_steps"
+        -> if the owner walked 69 steps, then it'll create a variable called:
+           "info_owner_steps:69"
     """
 
     name = "info"

tuxemon/event/actions/input_variable.py

@@ -17,28 +17,38 @@
 @dataclass
 class InputVariableAction(EventAction):
     """
-    Set a code and checks if it's correct or not.
+    Set a code and check if it's correct or not.
     The player's output will be by default lowercase.
 
     Script usage:
-        .. code-block::
 
-            input_variable <variable>,<question>[,answer][,escape]
+        .. code-block:: text
+
+           input_variable <variable>,<question>[,answer][,escape]
 
     Script parameters:
-        question: The question the player needs to reply (eg. "access_code")
-            then you create the msgid "access_code" inside the PO file:
+
+        question:
+            The question the player needs to reply (e.g. "access_code").
+            Then you create the msgid "access_code" inside the PO file:
+
                 msgid "access_code"
                 msgstr "Here the actual question?"
-        variable: Name of the variable where to store the output.
-        escape: Optional string flag ("true", "1", "yes" for True),
-            defaults to False when omitted
 
-    eg. "input_variable access_code,response_question"
-    eg. "input_variable access_code,response_question,escape"
+        variable:
+            Name of the variable where to store the output.
+
+        escape:
+            Optional string flag ("true", "1", "yes" for True),
+            defaults to False when omitted.
+
+    Examples:
+
+        "input_variable access_code,response_question"
+        "input_variable access_code,response_question,escape"
 
-    -> "is variable_set response_question:whatswrittenbytheplayer"
-    -> "not variable_set response_question:whatswrittenbytheplayer"
+        -> "is variable_set response_question:whatswrittenbytheplayer"
+        -> "not variable_set response_question:whatswrittenbytheplayer"
     """
 
     name = "input_variable"

tuxemon/event/actions/set_cipher.py

@@ -52,18 +52,21 @@ class SetCipherAction(EventAction):
     Toggles ciphering for dialogue by enabling or disabling the CipherProcessor.
 
     Script usage:
-        .. code-block::
-            set_cipher <option>,<cipher_map>
+
+        .. code-block:: text
+
+        set_cipher <option>,<cipher_map>
 
     Parameters:
+
         option:
-        - "enable": Activates ciphering using the provided cipher map (if any).
-        - "disable": Disables ciphering entirely.
+            - "enable": Activates ciphering using the provided cipher map (if any).
+            - "disable": Disables ciphering entirely.
 
-        cipher_map: the filename (without extension) of a YAML file located in
-            the mods folder.
-        - If omitted during "enable", the default cipher map is used.
-        - Ignored when option is "disable".
+        cipher_map:
+            The filename (without extension) of a YAML file located in the mods folder.
+            - If omitted during "enable", the default cipher map is used.
+            - Ignored when option is "disable".
     """
 
     name = "set_cipher"