Merge pull request #673 from Loup-Garou911XD/master

Sphinx docs generation

.github/workflows/cd.yml

@@ -206,3 +206,25 @@ jobs:
       with:
         name: windows_x86_server_(debug)
         path: build/prefab/full/windows_x86_server
+  make_sphinx_docs:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.11'
+    # Remove this once we upgrade to 3.12.
+    - name: Install typing_extensions (temp)
+      run: python3.11 -m pip install typing_extensions
+    - name: Install sphinx
+      run: python3.11 -m pip install sphinx furo
+    - name: Install pip requirements
+      run: tools/pcommand install_pip_reqs
+    - name: Make the build
+      run: make docs-sphinx
+    - name: Upload the build
+      uses: actions/upload-artifact@v3
+      with:
+        name: sphinx_html_docs
+        path: build/sphinx

CONTRIBUTORS.md

@@ -57,3 +57,7 @@
 
 ### brostos
 - Added support for joining using ipv6 address
+
+### Loup Garou
+- Added sphinx documentation generation
+

Makefile

@@ -183,6 +183,14 @@ docs:
 docs-pdoc:
 	@$(PCOMMAND) gen_docs_pdoc
 
+docs-sphinx:
+	$(MAKE) dummymodules
+	@$(PCOMMAND) gen_docs_sphinx
+
+docs-sphinx-clean:
+	rm -rf .cache/sphinx
+	rm -rf build/sphinx
+
 pcommandbatch_speed_test: prereqs
 	@$(PCOMMAND) pcommandbatch_speed_test $(PCOMMANDBATCH)
 

config/spinoffconfig.py

@@ -278,6 +278,7 @@ ctx.filter_file_extensions = {
     '.xcsettings',
     '.xcstrings',
     '.filters',
+    '.rst',
 }
 
 # ELSE files with these extensions will NOT be filtered.

src/assets/sphinx/template/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

src/assets/sphinx/template/conf.py

@@ -0,0 +1,65 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+import os
+import sys
+
+ballistica_root = os.getenv('BALLISTICA_ROOT') + '/'
+assets_dirs: dict = {
+    'ba_data': 'src/assets/ba_data/python/',
+    'dummy_modules': 'build/dummymodules/',
+    'efro_tools': 'tools/',  # for efro and bacommon package
+}
+
+sys.path.append(os.path.abspath(ballistica_root + assets_dirs['ba_data']))
+sys.path.append(os.path.abspath(ballistica_root + assets_dirs['dummy_modules']))
+sys.path.append(os.path.abspath(ballistica_root + assets_dirs['efro_tools']))
+
+# -- Options for HTML output -------------------------------------------------
+
+# for more themes visit https://sphinx-themes.org/
+html_theme = 'furo'  # python_docs_theme, groundwork, furo
+# html_logo = ballistica_root + 'build/assets/ba_data/textures/logo_preview.png' # need a smaller img
+
+
+# -- Project information -----------------------------------------------------
+
+keep_warnings = True  # Supressing warnings
+project = 'ballistica-bombsquad'
+
+copyright = '2024, Efroemling'
+author = 'Efroemling'
+
+# The full version, including alpha/beta/rc tags
+# TODO: make this update from some variable
+version = '1.7.33'
+release = '43241'
+
+# -- 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.
+autosummary_generate = True
+extensions = [
+    'sphinx.ext.napoleon',  # https://stackoverflow.com/questions/45880348/how-to-remove-the-cause-of-an-unexpected-indentation-warning-when-generating-cod
+    'sphinx.ext.autodoc',
+]
+
+# 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']
+
+
+# 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']

src/assets/sphinx/template/index.rst

@@ -0,0 +1,21 @@
+.. Bombsquad-docs documentation master file, created by
+   sphinx-quickstart on Sat Mar  2 18:31:19 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to Bombsquad-docs's documentation!
+==========================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   modules
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

src/assets/sphinx/template/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

tools/batools/docs.py

@@ -212,3 +212,65 @@ def _run_pdoc() -> None:
 
     duration = time.monotonic() - starttime
     print(f'{Clr.GRN}Generated pdoc documentation in {duration:.1f}s.{Clr.RST}')
+
+
+def generate_sphinxdoc() -> None:
+    """Generate a set of pdoc documentation."""
+    _run_sphinx()
+
+
+def _run_sphinx() -> None:
+    """Do the actual docs generation with sphinx."""
+    import time
+    import shutil
+
+    from batools.version import get_current_version
+
+    version, buildnum = get_current_version()
+
+    assets_dirs: dict = {
+        'ba_data': 'src/assets/ba_data/python/',
+        'dummy_modules': 'build/dummymodules/',
+        'efro_tools': 'tools/',  # for efro and bacommon package
+    }
+
+    sphinx_src = 'src/assets/sphinx/'
+    template_dir = Path(sphinx_src + 'template/')
+    assert template_dir.is_dir()
+    build_dir = 'build/sphinx/'
+    os.makedirs(build_dir, exist_ok=True)
+    sphinx_apidoc_out = '.cache/sphinx/'  # might want to use .cache dir
+    os.makedirs(sphinx_apidoc_out, exist_ok=True)
+
+    os.environ['BALLISTICA_ROOT'] = os.getcwd()  # used in sphinx conf.py
+    os.environ['BA_RUNNING_WITH_DUMMY_MODULES'] = '1'
+
+    shutil.copytree(template_dir, sphinx_apidoc_out, dirs_exist_ok=True)
+
+    starttime = time.monotonic()
+    apidoc_cmd = [
+        'sphinx-apidoc',
+        '-f',  # Force overwriting of any existing generated files.
+        '-H',
+        'Bombsquad',  # project
+        '-A',
+        'Efroemling',  # author
+        '-V',
+        str(version),  # version
+        '-R',
+        str(buildnum),  # release
+        # '--templatedir', template_dir,
+        '-o',
+        sphinx_apidoc_out,
+    ]
+    subprocess.run(apidoc_cmd + [assets_dirs['ba_data']], check=True)
+    subprocess.run(apidoc_cmd + [assets_dirs['dummy_modules']], check=True)
+    subprocess.run(apidoc_cmd + [assets_dirs['efro_tools']], check=True)
+
+    subprocess.run(['make', 'html'], check=True, cwd=sphinx_apidoc_out)
+    shutil.copytree(
+        sphinx_apidoc_out + '_build/html/', build_dir, dirs_exist_ok=True
+    )
+    # shutil.rmtree(temp_modules_dir)
+    duration = time.monotonic() - starttime
+    print(f'Generated sphinx documentation in {duration:.1f}s.')

tools/batools/pcommands.py

@@ -562,6 +562,13 @@ def gen_docs_pdoc() -> None:
     batools.docs.generate_pdoc(projroot=str(pcommand.PROJROOT))
 
 
+def gen_docs_sphinx() -> None:
+    """Generate sphinx documentation."""
+    import batools.docs
+
+    batools.docs.generate_sphinxdoc()
+
+
 def list_pip_reqs() -> None:
     """List Python Pip packages needed for this project."""
     from batools.build import get_pip_reqs

tools/batools/spinoff/_context.py

@@ -1563,7 +1563,11 @@ class SpinoffContext:
                 os.remove(delete_file_name)
 
     def _is_project_file(self, path: str) -> bool:
-        if path.startswith('tools/') or path.startswith('src/external'):
+        if (
+            path.startswith('tools/')
+            or path.startswith('src/external')
+            or path.startswith('src/assets/sphinx')
+        ):
             return False
         bname = os.path.basename(path)
         return (

tools/pcommand

@@ -99,6 +99,7 @@ from batools.pcommands import (
     get_modern_make,
     warm_start_asset_build,
     gen_docs_pdoc,
+    gen_docs_sphinx,
     list_pip_reqs,
     install_pip_reqs,
     checkenv,