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

@@ -5,11 +5,21 @@
 # Required
 version: 2
 
+# Required
+version: 2
+
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: docs/conf.py
 
 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,100 @@
 # 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
+from tuxemon.constants.paths import LIBDIR
 
+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'
 
 # The full version, including alpha/beta/rc tags
+# 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',
+    'script_documenter', 
 ]
 
 # Add any paths that contain templates here, relative to this directory.
 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.
-#
+# 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".
+# 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")
 ]
 
 
-# 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:
+    """Connect the run_apidoc function to the 'builder-inited' Sphinx event."""
     app.connect('builder-inited', run_apidoc)