mirror of
https://github.com/RYDE-WORK/ballistica.git
synced 2026-01-23 07:23:19 +08:00
Merge pull request #683 from Loup-Garou911XD/master
Improvements to sphinx docs
This commit is contained in:
Eric Froemling
GitHub
commit
a2bcf8fa23
@ -45,7 +45,8 @@
|
||||
"pbxproj.XcodeProject",
|
||||
"pbxproj.pbxextensions",
|
||||
"openstep_parser",
|
||||
"daemon"
|
||||
"daemon",
|
||||
"jinja2"
|
||||
],
|
||||
"python_paths": [
|
||||
"src/assets/ba_data/python",
|
||||
|
||||
@ -278,7 +278,7 @@ ctx.filter_file_extensions = {
|
||||
'.xcsettings',
|
||||
'.xcstrings',
|
||||
'.filters',
|
||||
'.rst',
|
||||
'.rst_t',
|
||||
}
|
||||
|
||||
# ELSE files with these extensions will NOT be filtered.
|
||||
|
||||
@ -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.
|
||||
@ -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)
|
||||
@ -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
|
||||
@ -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
|
||||
@ -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]),
|
||||
]
|
||||
|
||||
|
||||
|
||||
@ -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.')
|
||||
|
||||
@ -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 (
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user