switched to sphinx-build instead of make file

config/spinoffconfig.py

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

src/assets/sphinx/static/Makefile

@@ -1,20 +0,0 @@
-# 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/static/make.bat

@@ -1,35 +0,0 @@
-@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

src/assets/sphinx/template/index.rst_t

@@ -3,7 +3,7 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
    
-   see https://pradyunsg.me/furo/reference/ for formatting help
+   see https://pradyunsg.me/furo/reference/ and https://en.wikipedia.org/wiki/ReStructuredText for formatting help
 .. image:: {{data.ballistica_image_url}}
 
 Welcome to ballistica-bombsquad's documentation!
@@ -23,4 +23,4 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 
-.. note:: For customization of this page see https://github.com/efroemling/ballistica/blob/master/src/assets/sphinx/template/index.rst
+.. note:: For customization of this page see https://github.com/efroemling/ballistica/blob/master/src/assets/sphinx/template/index.rst_t

tools/batools/build.py

@@ -65,6 +65,7 @@ PY_REQUIREMENTS = [
     PyRequirement(pipname='python-daemon', minversion=[3, 0, 1]),
     PyRequirement(pipname='Sphinx', minversion=[7, 2, 6]),
     PyRequirement(pipname='furo', minversion=[2024, 0o1, 29]),
+    PyRequirement(pipname='Jinja2', minversion=[3, 1, 2]),
 ]
 
 

tools/batools/docs.py

@@ -241,18 +241,23 @@ def _run_sphinx(
         'dummy_modules': 'build/dummymodules/',
         'efro_tools': 'tools/',  # for efro and bacommon package
     }
-
+    paths: dict = {
-    paths = {'sphinx_src' :'src/assets/sphinx/',
+        'sphinx_src': 'src/assets/sphinx/',
-             'build_dir' : 'build/sphinx/',
+        'build_dir': 'build/sphinx/',
-             'sphinx_apidoc_out' : '.cache/sphinx/',
+        'sphinx_cache_dir': '.cache/sphinx/',
-            }
+    }
-    paths.update({'template_dir' : paths['sphinx_src'] + 'template/',
+    paths.update(
-                  'static_dir' : paths['sphinx_src'] + 'static/'})
+        {
+            'template_dir': paths['sphinx_src'] + 'template/',
+            'static_dir': paths['sphinx_src'] + 'static/',
+        }
+    )
 
     assert Path(paths['template_dir']).is_dir()
+    assert Path(paths['static_dir']).is_dir()
 
     os.makedirs(paths['build_dir'], exist_ok=True)
-    os.makedirs(paths['sphinx_apidoc_out'], exist_ok=True)
+    os.makedirs(paths['sphinx_cache_dir'], exist_ok=True)
 
     os.environ['BALLISTICA_ROOT'] = os.getcwd()  # used in sphinx conf.py
     os.environ['BA_RUNNING_WITH_DUMMY_MODULES'] = '1'
@@ -266,19 +271,21 @@ def _run_sphinx(
         }
     )
 
+
     file_loader = FileSystemLoader(paths['template_dir'])
     env = Environment(loader=file_loader)
-    index_template =  env.get_template('index.rst_t')
+    index_template = env.get_template('index.rst_t')
-
     # maybe make it automatically render all files in templates dir in future
-    with open(paths['sphinx_apidoc_out']+'index.rst', 'w') as index_rst:
+    with open(
-        data = {'ballistica_image_url' : 'https://camo.githubusercontent.com/25021344ceaa7def6fa6523f79115f7ffada8d26b4768bb9a0cf65fc33304f45/68747470733a2f2f66696c65732e62616c6c6973746963612e6e65742f62616c6c6973746963615f6d656469612f62616c6c6973746963615f6c6f676f5f68616c662e706e67',
+        paths['sphinx_cache_dir'] + 'index.rst', 'w', encoding='utf-8'
-            'version_no' : version,
+    ) as index_rst:
-            'build_no' : str(buildnum)}
+        data = {
+            'ballistica_image_url': 'https://camo.githubusercontent.com/25021344ceaa7def6fa6523f79115f7ffada8d26b4768bb9a0cf65fc33304f45/68747470733a2f2f66696c65732e62616c6c6973746963612e6e65742f62616c6c6973746963615f6d656469612f62616c6c6973746963615f6c6f676f5f68616c662e706e67',  # pylint: disable=line-too-long
+            'version_no': version,
+            'build_no': str(buildnum),
+        }
         index_rst.write(index_template.render(data=data))
 
-    shutil.copytree(paths['sphinx_src']+'static/', paths['sphinx_apidoc_out'], dirs_exist_ok=True)
-
     starttime = time.monotonic()
     apidoc_cmd = [
         'sphinx-apidoc',
@@ -293,8 +300,9 @@ def _run_sphinx(
         str(buildnum),  # release
         # '--templatedir', template_dir,
         '-o',
-        paths['sphinx_apidoc_out'],
+        paths['sphinx_cache_dir'],
     ]
+
     if generate_dummymodules_doc:
         subprocess.run(
             apidoc_cmd + [assets_dirs['dummy_modules']] + ['--private'],
@@ -302,12 +310,26 @@ def _run_sphinx(
         )
     if generate_tools_doc:
         subprocess.run(apidoc_cmd + [assets_dirs['efro_tools']], check=True)
-    subprocess.run(apidoc_cmd + [assets_dirs['ba_data']], check=True)
+    subprocess.run(apidoc_cmd + [assets_dirs['ba_data'], '-f'], check=True)
+    # -f for regenerating index page so it contains the ba_data modules
 
-    subprocess.run(['make', 'html'], check=True, cwd=paths['sphinx_apidoc_out'])
+    subprocess.run(
-    shutil.copytree( # copying html builds from sphinx_apidoc_out to the final build_dir
+        [
-        paths['sphinx_apidoc_out'] + '_build/html/', paths['build_dir'], dirs_exist_ok=True
+            'sphinx-build',
+            '-c', # config file dir
+            paths['static_dir'],
+            paths['sphinx_cache_dir'],  # input dir
+            paths['build_dir'],  # output dir
+            # enable after sphinx 7.3.0 is available on PyPi(pip)
+            # '--doctree-dir', paths['sphinx_cache_dir'],
+            # '-Q', #quiet now
+        ],
+        check=True,
     )
 
+    # slows down build process when rebuilding,
+    # remove after sphinx 7.3.0 is available on PyPi(pip)
+    shutil.rmtree(paths['build_dir']+'.doctrees')
+
     duration = time.monotonic() - starttime
     print(f'Generated sphinx documentation in {duration:.1f}s.')

tools/batools/spinoff/_context.py

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