Merge pull request #687 from Loup-Garou911XD/master

Improvements to sphinx docs and updated github actions

.github/workflows/cd.yml

@@ -19,7 +19,7 @@ jobs:
     - name: Make the build
       run: make prefab-gui-debug-build
     - name: Upload the build
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: linux_x86_64_gui_(debug)
         path: build/prefab/full/linux_x86_64_gui
@@ -36,7 +36,7 @@ jobs:
     - name: Make the build
       run: make prefab-server-debug-build
     - name: Upload the build
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: linux_x86_64_server_(debug)
         path: build/prefab/full/linux_x86_64_server
@@ -53,7 +53,7 @@ jobs:
     - name: Make the build
       run: make prefab-linux-arm64-gui-debug-build
     - name: Upload the build
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: linux_arm64_gui_(debug)
         path: build/prefab/full/linux_arm64_gui
@@ -70,7 +70,7 @@ jobs:
     - name: Make the build
       run: make prefab-linux-arm64-server-debug-build
     - name: Upload the build
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: linux_arm64_server_(debug)
         path: build/prefab/full/linux_arm64_server
@@ -87,7 +87,7 @@ jobs:
     - name: Make the build
       run: make prefab-mac-x86-64-gui-debug-build
     - name: Upload the build
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: mac_x86_64_gui_(debug)
         path: build/prefab/full/mac_x86_64_gui
@@ -104,7 +104,7 @@ jobs:
     - name: Make the build
       run: make prefab-mac-x86-64-server-debug-build
     - name: Upload the build
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: mac_x86_64_server_(debug)
         path: build/prefab/full/mac_x86_64_server
@@ -121,7 +121,7 @@ jobs:
     - name: Make the build
       run: make prefab-mac-arm64-gui-debug-build
     - name: Upload the build
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: mac_arm64_gui_(debug)
         path: build/prefab/full/mac_arm64_gui
@@ -138,7 +138,7 @@ jobs:
     - name: Make the build
       run: make prefab-mac-arm64-server-debug-build
     - name: Upload the build
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: mac_arm64_server_(debug)
         path: build/prefab/full/mac_arm64_server
@@ -155,7 +155,7 @@ jobs:
     - name: Make the build
       run: make prefab-windows-x86-gui-debug-build
     - name: Upload the build
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: windows_x86_gui_(debug)
         path: build/prefab/full/windows_x86_gui
@@ -172,7 +172,7 @@ jobs:
     - name: Make the build
       run: make prefab-windows-x86-server-debug-build
     - name: Upload the build
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: windows_x86_server_(debug)
         path: build/prefab/full/windows_x86_server
@@ -189,7 +189,7 @@ jobs:
     - name: Make the build
       run: make docs-sphinx
     - name: Upload the build
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: sphinx_html_docs
         path: build/sphinx

src/assets/sphinx/static/conf.py

@@ -21,10 +21,20 @@ 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']))
 
+# -- Project information -----------------------------------------------------
+project = sphinx_settings['project_name']
+copyright = sphinx_settings['copyright']
+author = sphinx_settings['project_author']
+# The full version, including alpha/beta/rc tags
+version = str(sphinx_settings['version'])
+release = str(sphinx_settings['buildnum'])
+
+
 # -- 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'
+html_title = project + ' ' + version + ' documentation'
+html_show_sphinx = False
 
 # do not remove, sets the logo on side panel
 html_logo = sphinx_settings['ballistica_logo']
@@ -55,28 +65,23 @@ if html_theme == 'furo':
         'navigation_with_keys': True,
     }
 
-    
-
-
-# -- Project information -----------------------------------------------------
-project = sphinx_settings['project_name']
-copyright = sphinx_settings['copyright']
-author = sphinx_settings['project_author']
-# The full version, including alpha/beta/rc tags
-version = str(sphinx_settings['version'])
-release = str(sphinx_settings['buildnum'])
-
 # -- General configuration ---------------------------------------------------
 
-# Add any Sphinx extension module names here, as strings. They can be
+# append to pages
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+rst_epilog = """
-# ones.
+"""
-
+# prepend to pages
-intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}   
+rst_prolog = f"""
+.. image:: {html_logo}
+    :target: index.html
+    :alt: Ballistica Logo 
+"""
+# 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.napoleon',
     'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
     # might want to use this in future
     # for linking with efro and bacommon packages
     'sphinx.ext.intersphinx',

src/assets/sphinx/template/index.rst_t

@@ -4,7 +4,6 @@
    contain the root `toctree` directive.
    
    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!
 ================================================

tools/batools/docs.py

@@ -279,7 +279,7 @@ def _run_sphinx(
         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
+            # 'ballistica_image_url': 'https://camo.githubusercontent.com/25021344ceaa7def6fa6523f79115f7ffada8d26b4768bb9a0cf65fc33304f45/68747470733a2f2f66696c65732e62616c6c6973746963612e6e65742f62616c6c6973746963615f6d656469612f62616c6c6973746963615f6c6f676f5f68616c662e706e67',  # pylint: disable=line-too-long
             'version_no': version,
             'build_no': str(buildnum),
         }