diff --git a/src/assets/sphinx/template/conf.py b/src/assets/sphinx/template/conf.py index 9d407c28..b0ff2933 100644 --- a/src/assets/sphinx/template/conf.py +++ b/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': """ + + + + """, + '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 = '1.7.33' -release = '43241' +version = str(sphinx_settings['version']) +release = str(sphinx_settings['buildnum']) # -- General configuration --------------------------------------------------- diff --git a/src/assets/sphinx/template/index.rst b/src/assets/sphinx/template/index.rst index 0b21db62..327d5da9 100644 --- a/src/assets/sphinx/template/index.rst +++ b/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. + + see https://pradyunsg.me/furo/reference/ for formatting help +.. image:: https://camo.githubusercontent.com/25021344ceaa7def6fa6523f79115f7ffada8d26b4768bb9a0cf65fc33304f45/68747470733a2f2f66696c65732e62616c6c6973746963612e6e65742f62616c6c6973746963615f6d656469612f62616c6c6973746963615f6c6f676f5f68616c662e706e67 -Welcome to Bombsquad-docs's documentation! -========================================== - +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 diff --git a/tools/batools/docs.py b/tools/batools/docs.py index 0b5ee88c..36e0216f 100755 --- a/tools/batools/docs.py +++ b/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(