Merge pull request #683 from Loup-Garou911XD/master

Improvements to sphinx docs

config/projectconfig.json

@@ -45,7 +45,8 @@
     "pbxproj.XcodeProject",
     "pbxproj.pbxextensions",
     "openstep_parser",
-    "daemon"
+    "daemon",
+    "jinja2"
   ],
   "python_paths": [
     "src/assets/ba_data/python",

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/conf.py

@@ -22,11 +22,12 @@ 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, sphinx_rtd_theme 
 html_title = sphinx_settings['project_name'] + ' ' + str(sphinx_settings['version']) + ' documentation'
-# for more themes visit https://sphinx-themes.org/
 
-html_logo = 'https://camo.githubusercontent.com/25021344ceaa7def6fa6523f79115f7ffada8d26b4768bb9a0cf65fc33304f45/68747470733a2f2f66696c65732e62616c6c6973746963612e6e65742f62616c6c6973746963615f6d656469612f62616c6c6973746963615f6c6f676f5f68616c662e706e67'
+# do not remove, sets the logo on side panel
+html_logo = sphinx_settings['ballistica_logo']
 
 if html_theme == 'furo':
     html_theme_options = {
@@ -58,9 +59,6 @@ if html_theme == 'furo':
 
 
 # -- Project information -----------------------------------------------------
-
-keep_warnings = True  # Supressing warnings
-
 project = sphinx_settings['project_name']
 copyright = sphinx_settings['copyright']
 author = sphinx_settings['project_author']
@@ -73,10 +71,15 @@ release = str(sphinx_settings['buildnum'])
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
+
+intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}   
 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',
+    # might want to use this in future
+    # for linking with efro and bacommon packages
+    'sphinx.ext.intersphinx',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

src/assets/sphinx/template/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/template/index.rst_t

@@ -3,11 +3,13 @@
    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:: https://camo.githubusercontent.com/25021344ceaa7def6fa6523f79115f7ffada8d26b4768bb9a0cf65fc33304f45/68747470733a2f2f66696c65732e62616c6c6973746963612e6e65742f62616c6c6973746963615f6d656469612f62616c6c6973746963615f6c6f676f5f68616c662e706e67
+.. image:: {{data.ballistica_image_url}}
 
 Welcome to ballistica-bombsquad's documentation!
 ================================================
+*Last updated for Ballistica* **{{data.version_no}}** *(build {{data.build_no}})*
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
@@ -21,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

src/assets/sphinx/template/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

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

@@ -231,8 +231,8 @@ def _run_sphinx(
 
     import time
     import shutil
-
     from batools.version import get_current_version
+    from jinja2 import Environment, FileSystemLoader
 
     version, buildnum = get_current_version()
 
@@ -241,16 +241,26 @@ def _run_sphinx(
         'dummy_modules': 'build/dummymodules/',
         'efro_tools': 'tools/',  # for efro and bacommon package
     }
+    paths: dict = {
+        'sphinx_src': 'src/assets/sphinx/',
+        'build_dir': 'build/sphinx/',
+        'sphinx_cache_dir': '.cache/sphinx/',
+    }
+    paths.update(
+        {
+            'template_dir': paths['sphinx_src'] + 'template/',
+            'static_dir': paths['sphinx_src'] + 'static/',
+        }
+    )
 
-    sphinx_src = 'src/assets/sphinx/'
+    assert Path(paths['template_dir']).is_dir()
-    template_dir = Path(sphinx_src + 'template/')
+    assert Path(paths['static_dir']).is_dir()
-    assert template_dir.is_dir()
+
-    build_dir = 'build/sphinx/'
+    os.makedirs(paths['build_dir'], exist_ok=True)
-    os.makedirs(build_dir, exist_ok=True)
+    os.makedirs(paths['sphinx_cache_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'
     os.environ['SPHINX_SETTINGS'] = str(
         {
             'project_name': project_name,
@@ -258,16 +268,28 @@ def _run_sphinx(
             'copyright': copyright_text,
             'version': version,
             'buildnum': buildnum,
+            'ballistica_logo': 'https://camo.githubusercontent.com/25021344ceaa7def6fa6523f79115f7ffada8d26b4768bb9a0cf65fc33304f45/68747470733a2f2f66696c65732e62616c6c6973746963612e6e65742f62616c6c6973746963615f6d656469612f62616c6c6973746963615f6c6f676f5f68616c662e706e67',  # pylint: disable=line-too-long
         }
     )
-    os.environ['BA_RUNNING_WITH_DUMMY_MODULES'] = '1'
 
-    shutil.copytree(template_dir, sphinx_apidoc_out, dirs_exist_ok=True)
+    file_loader = FileSystemLoader(paths['template_dir'])
+    env = Environment(loader=file_loader)
+    index_template = env.get_template('index.rst_t')
+    # maybe make it automatically render all files in templates dir in future
+    with open(
+        paths['sphinx_cache_dir'] + 'index.rst', 'w', encoding='utf-8'
+    ) as index_rst:
+        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))
 
     starttime = time.monotonic()
     apidoc_cmd = [
         'sphinx-apidoc',
-        '-f',  # Force overwriting of any existing generated files.
+        # '-f',  # Force overwriting of any existing generated files.
         '-H',
         project_name,
         '-A',
@@ -278,8 +300,9 @@ def _run_sphinx(
         str(buildnum),  # release
         # '--templatedir', template_dir,
         '-o',
-        sphinx_apidoc_out,
+        paths['sphinx_cache_dir'],
     ]
+
     if generate_dummymodules_doc:
         subprocess.run(
             apidoc_cmd + [assets_dirs['dummy_modules']] + ['--private'],
@@ -287,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=sphinx_apidoc_out)
+    subprocess.run(
-    shutil.copytree(
+        [
-        sphinx_apidoc_out + '_build/html/', 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,
     )
-    # shutil.rmtree(temp_modules_dir)
+
+    # 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 (