diff --git a/config/projectconfig.json b/config/projectconfig.json index 68dd6d90..92d5d235 100644 --- a/config/projectconfig.json +++ b/config/projectconfig.json @@ -45,7 +45,8 @@ "pbxproj.XcodeProject", "pbxproj.pbxextensions", "openstep_parser", - "daemon" + "daemon", + "jinja2" ], "python_paths": [ "src/assets/ba_data/python", diff --git a/config/spinoffconfig.py b/config/spinoffconfig.py index 6844d1c5..4632332a 100644 --- a/config/spinoffconfig.py +++ b/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. diff --git a/src/assets/sphinx/template/conf.py b/src/assets/sphinx/static/conf.py similarity index 93% rename from src/assets/sphinx/template/conf.py rename to src/assets/sphinx/static/conf.py index b0ff2933..7dfdb1ad 100644 --- a/src/assets/sphinx/template/conf.py +++ b/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. diff --git a/src/assets/sphinx/template/Makefile b/src/assets/sphinx/template/Makefile deleted file mode 100644 index d4bb2cbb..00000000 --- a/src/assets/sphinx/template/Makefile +++ /dev/null @@ -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) diff --git a/src/assets/sphinx/template/index.rst b/src/assets/sphinx/template/index.rst_t similarity index 64% rename from src/assets/sphinx/template/index.rst rename to src/assets/sphinx/template/index.rst_t index 327d5da9..3ebebcfa 100644 --- a/src/assets/sphinx/template/index.rst +++ b/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 -.. image:: https://camo.githubusercontent.com/25021344ceaa7def6fa6523f79115f7ffada8d26b4768bb9a0cf65fc33304f45/68747470733a2f2f66696c65732e62616c6c6973746963612e6e65742f62616c6c6973746963615f6d656469612f62616c6c6973746963615f6c6f676f5f68616c662e706e67 + 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! ================================================ +*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 diff --git a/src/assets/sphinx/template/make.bat b/src/assets/sphinx/template/make.bat deleted file mode 100644 index 32bb2452..00000000 --- a/src/assets/sphinx/template/make.bat +++ /dev/null @@ -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 diff --git a/tools/batools/build.py b/tools/batools/build.py index b7c54495..f20c01c3 100644 --- a/tools/batools/build.py +++ b/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]), ] diff --git a/tools/batools/docs.py b/tools/batools/docs.py index 36e0216f..a592f669 100755 --- a/tools/batools/docs.py +++ b/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/' - template_dir = Path(sphinx_src + 'template/') - assert template_dir.is_dir() - build_dir = 'build/sphinx/' - os.makedirs(build_dir, exist_ok=True) - sphinx_apidoc_out = '.cache/sphinx/' # might want to use .cache dir - os.makedirs(sphinx_apidoc_out, exist_ok=True) + assert Path(paths['template_dir']).is_dir() + assert Path(paths['static_dir']).is_dir() + + os.makedirs(paths['build_dir'], exist_ok=True) + os.makedirs(paths['sphinx_cache_dir'], 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) - shutil.copytree( - sphinx_apidoc_out + '_build/html/', build_dir, dirs_exist_ok=True + subprocess.run( + [ + '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.') diff --git a/tools/batools/spinoff/_context.py b/tools/batools/spinoff/_context.py index b0870822..d61b7486 100644 --- a/tools/batools/spinoff/_context.py +++ b/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 ( - path.startswith('tools/') - or path.startswith('src/external') - or path.startswith('src/assets/sphinx') - ): + if path.startswith('tools/') or path.startswith('src/external'): return False bname = os.path.basename(path) return (