From 43979e1408cfad5d38be60c24344f7549c5e2dd3 Mon Sep 17 00:00:00 2001 From: Loup-Garou911XD Date: Tue, 19 Mar 2024 19:09:33 +0530 Subject: [PATCH] switched to sphinx-build instead of make file --- config/spinoffconfig.py | 2 +- src/assets/sphinx/static/Makefile | 20 -------- src/assets/sphinx/static/make.bat | 35 ------------- src/assets/sphinx/template/index.rst_t | 4 +- tools/batools/build.py | 1 + tools/batools/docs.py | 68 +++++++++++++++++--------- tools/batools/spinoff/_context.py | 6 +-- 7 files changed, 50 insertions(+), 86 deletions(-) delete mode 100644 src/assets/sphinx/static/Makefile delete mode 100644 src/assets/sphinx/static/make.bat 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/static/Makefile b/src/assets/sphinx/static/Makefile deleted file mode 100644 index d4bb2cbb..00000000 --- a/src/assets/sphinx/static/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/static/make.bat b/src/assets/sphinx/static/make.bat deleted file mode 100644 index 32bb2452..00000000 --- a/src/assets/sphinx/static/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/src/assets/sphinx/template/index.rst_t b/src/assets/sphinx/template/index.rst_t index eb99b1a1..3ebebcfa 100644 --- a/src/assets/sphinx/template/index.rst_t +++ b/src/assets/sphinx/template/index.rst_t @@ -3,7 +3,7 @@ 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 + 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! @@ -23,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/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 b7a53692..1c6b5fa3 100755 --- a/tools/batools/docs.py +++ b/tools/batools/docs.py @@ -241,18 +241,23 @@ 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/', + } + ) - paths = {'sphinx_src' :'src/assets/sphinx/', - 'build_dir' : 'build/sphinx/', - 'sphinx_apidoc_out' : '.cache/sphinx/', - } - paths.update({'template_dir' : paths['sphinx_src'] + 'template/', - 'static_dir' : paths['sphinx_src'] + 'static/'}) - 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_apidoc_out'], 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' @@ -265,20 +270,22 @@ def _run_sphinx( 'buildnum': buildnum, } ) - + + file_loader = FileSystemLoader(paths['template_dir']) env = Environment(loader=file_loader) - index_template = env.get_template('index.rst_t') - + index_template = env.get_template('index.rst_t') # maybe make it automatically render all files in templates dir in future - with open(paths['sphinx_apidoc_out']+'index.rst', 'w') as index_rst: - data = {'ballistica_image_url' : 'https://camo.githubusercontent.com/25021344ceaa7def6fa6523f79115f7ffada8d26b4768bb9a0cf65fc33304f45/68747470733a2f2f66696c65732e62616c6c6973746963612e6e65742f62616c6c6973746963615f6d656469612f62616c6c6973746963615f6c6f676f5f68616c662e706e67', - 'version_no' : version, - 'build_no' : str(buildnum)} + 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)) - shutil.copytree(paths['sphinx_src']+'static/', paths['sphinx_apidoc_out'], dirs_exist_ok=True) - starttime = time.monotonic() apidoc_cmd = [ 'sphinx-apidoc', @@ -293,8 +300,9 @@ def _run_sphinx( str(buildnum), # release # '--templatedir', template_dir, '-o', - paths['sphinx_apidoc_out'], + paths['sphinx_cache_dir'], ] + if generate_dummymodules_doc: subprocess.run( apidoc_cmd + [assets_dirs['dummy_modules']] + ['--private'], @@ -302,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=paths['sphinx_apidoc_out']) - shutil.copytree( # copying html builds from sphinx_apidoc_out to the final build_dir - paths['sphinx_apidoc_out'] + '_build/html/', paths['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, ) + # 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 (