Improvements to sphinx docs

src/assets/sphinx/template/conf.py

@@ -8,7 +8,9 @@
 import os
 import sys
 
+sphinx_settings = eval(os.getenv('SPHINX_SETTINGS')) # set in tools/batools/docs.py
 ballistica_root = os.getenv('BALLISTICA_ROOT') + '/'
+
 assets_dirs: dict = {
     'ba_data': 'src/assets/ba_data/python/',
     'dummy_modules': 'build/dummymodules/',
@@ -20,24 +22,51 @@ 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 -------------------------------------------------
-
+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_theme = 'furo'  # python_docs_theme, groundwork, furo
+
-# html_logo = ballistica_root + 'build/assets/ba_data/textures/logo_preview.png' # need a smaller img
+html_logo = 'https://camo.githubusercontent.com/25021344ceaa7def6fa6523f79115f7ffada8d26b4768bb9a0cf65fc33304f45/68747470733a2f2f66696c65732e62616c6c6973746963612e6e65742f62616c6c6973746963615f6d656469612f62616c6c6973746963615f6c6f676f5f68616c662e706e67'
+
+if html_theme == 'furo':
+    html_theme_options = {
+        'announcement': 'This is a placeholder announcement',
+        'light_css_variables': {
+            'color-brand-primary': '#3cda0b',
+            'color-brand-content': '#7C4DFF',
+        },
+        'dark_css_variables': {
+            'color-brand-primary': '#3cda0b',
+            'color-brand-content': '#7C4DFF',
+        },
+        'footer_icons': [{
+                'name': 'GitHub',
+                'url': 'https://github.com/efroemling/ballistica/',
+                'html': """
+                    <svg stroke='currentColor' fill='currentColor' stroke-width='0' viewBox='0 0 16 16'>
+                        <path fill-rule='evenodd' d='M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z'></path>
+                    </svg>
+                """,
+                'class': '',
+                },
+            ],
+        'top_of_page_button': 'edit',
+        'navigation_with_keys': True,
+    }
+
+    
 
 
 # -- Project information -----------------------------------------------------
 
 keep_warnings = True  # Supressing warnings
-project = 'ballistica-bombsquad'
-
-copyright = '2024, Efroemling'
-author = 'Efroemling'
 
+project = sphinx_settings['project_name']
+copyright = sphinx_settings['copyright']
+author = sphinx_settings['project_author']
 # The full version, including alpha/beta/rc tags
-# TODO: make this update from some variable
+version = str(sphinx_settings['version'])
-version = '1.7.33'
+release = str(sphinx_settings['buildnum'])
-release = '43241'
 
 # -- General configuration ---------------------------------------------------
 

src/assets/sphinx/template/index.rst

@@ -1,11 +1,13 @@
-.. Bombsquad-docs documentation master file, created by
+.. Bombsquad 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!
+   see https://pradyunsg.me/furo/reference/ for formatting help
-==========================================
+.. image:: https://camo.githubusercontent.com/25021344ceaa7def6fa6523f79115f7ffada8d26b4768bb9a0cf65fc33304f45/68747470733a2f2f66696c65732e62616c6c6973746963612e6e65742f62616c6c6973746963615f6d656469612f62616c6c6973746963615f6c6f676f5f68616c662e706e67
 
+Welcome to ballistica-bombsquad's documentation!
+================================================
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
@@ -18,4 +20,5 @@ Indices and tables
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`
+
+.. note:: For customization of this page see https://github.com/efroemling/ballistica/blob/master/src/assets/sphinx/template/index.rst

tools/batools/docs.py

@@ -219,8 +219,16 @@ def generate_sphinxdoc() -> None:
     _run_sphinx()
 
 
-def _run_sphinx() -> None:
+def _run_sphinx(
+    project_name: str = 'ballistica',
+    project_author: str = 'Efroemling',
+    copyright_text: str = '2024, Efroemling',
+    generate_dummymodules_doc: bool = True,
+    generate_tools_doc: bool = True,
+) -> None:
     """Do the actual docs generation with sphinx."""
+    # pylint: disable=too-many-locals
+
     import time
     import shutil
 
@@ -243,6 +251,15 @@ def _run_sphinx() -> None:
     os.makedirs(sphinx_apidoc_out, exist_ok=True)
 
     os.environ['BALLISTICA_ROOT'] = os.getcwd()  # used in sphinx conf.py
+    os.environ['SPHINX_SETTINGS'] = str(
+        {
+            'project_name': project_name,
+            'project_author': project_author,
+            'copyright': copyright_text,
+            'version': version,
+            'buildnum': buildnum,
+        }
+    )
     os.environ['BA_RUNNING_WITH_DUMMY_MODULES'] = '1'
 
     shutil.copytree(template_dir, sphinx_apidoc_out, dirs_exist_ok=True)
@@ -252,9 +269,9 @@ def _run_sphinx() -> None:
         'sphinx-apidoc',
         '-f',  # Force overwriting of any existing generated files.
         '-H',
-        'Bombsquad',  # project
+        project_name,
         '-A',
-        'Efroemling',  # author
+        project_author,
         '-V',
         str(version),  # version
         '-R',
@@ -263,9 +280,14 @@ def _run_sphinx() -> None:
         '-o',
         sphinx_apidoc_out,
     ]
+    if generate_dummymodules_doc:
+        subprocess.run(
+            apidoc_cmd + [assets_dirs['dummy_modules']] + ['--private'],
+            check=True,
+        )
+    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['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(