mirror of
https://github.com/RYDE-WORK/ballistica.git
synced 2026-01-23 07:23:19 +08:00
Improvements to sphinx docs
This commit is contained in:
Loup-Garou911XD
parent
edd4f919d7
commit
a8b3ed34fe
@ -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 = '1.7.33'
|
||||
release = '43241'
|
||||
version = str(sphinx_settings['version'])
|
||||
release = str(sphinx_settings['buildnum'])
|
||||
|
||||
# -- General configuration ---------------------------------------------------
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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(
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user