<'
- 'all methods inherited from ' +
- self._get_type_display(par) + '>\n')
- else:
- self._write_inherited_methods_for_class(cls)
- self._write_methods_for_class(cls, methods)
-
- def _gather_funcs(self, module: ModuleType) -> None:
- import types
- import pydoc
-
- # Function, build-in-function.
- func_types = [types.FunctionType, types.BuiltinMethodType]
-
- names = dir(module)
- funcs = [
- getattr(module, name) for name in names if not name.startswith('_')
- ]
- funcs = [f for f in funcs if any(isinstance(f, t) for t in func_types)]
-
- for fnc in funcs:
-
- # For non-builtin funcs, use the pydoc rendering since it includes
- # args.
- # Chop off the first line which is just "Python Library
- # Documentation: and the second which is blank.
- docs = None
- if isinstance(fnc, types.FunctionType):
- docslines = pydoc.plain(pydoc.render_doc(fnc)).splitlines()[2:]
-
- # Pydoc indents all lines but the first 4 spaces; undo that.
- for i, line in enumerate(docslines):
- if i != 0:
- if not line.startswith(' '):
- raise Exception('UNEXPECTED')
- docslines[i] = line[4:]
-
- # Add an empty line after the first.
- docslines = [docslines[0]] + [''] + docslines[1:]
-
- if len(docslines) == 2:
- docslines.append('(no docs)')
- self._errors.append(fnc)
- docs = '\n'.join(docslines)
- else:
- if fnc.__doc__ is not None:
- docs = fnc.__doc__
- else:
- fnc.__doc__ = '(no docs)'
- self._errors.append(fnc)
- assert docs is not None
-
- f_info = FunctionInfo(name=fnc.__module__ + '.' + fnc.__name__,
- category=_get_category(
- docs, CategoryType.FUNCTION),
- docs=docs)
- if '(internal)' not in docs:
- self._functions.append(f_info)
-
- def _process_classes(self, module: ModuleType) -> None:
- classes_by_name = _get_module_classes(module)
- for c_name, cls in classes_by_name:
- docs = self._get_base_docs_for_class(cls)
- bases = _get_bases(cls)
- methods, inherited_methods = self._get_methods_for_class(cls)
- enum_values = self._get_enum_values_for_class(cls)
- docs, attrs = self._get_all_attrs_for_class(cls, docs)
-
- c_info = ClassInfo(name=c_name,
- parents=bases,
- docs=docs,
- enum_values=enum_values,
- methods=methods,
- inherited_methods=inherited_methods,
- category=_get_category(docs,
- CategoryType.CLASS),
- attributes=attrs)
- self._classes.append(c_info)
-
- def _write_category_list(self) -> None:
- for cname, ctype, cmembers in self._merged_categories:
- if ctype == 'class':
- assert (isinstance(i, ClassInfo) for i in cmembers)
- cssclass = ' class="offsanchor"' if DO_CSS_CLASSES else ''
- self._out += (f'' + cname +
- '
\n')
- classes_sorted = cast(list[ClassInfo], cmembers)
- classes_sorted.sort(key=lambda x: x.name.lower())
- pcc = _print_child_classes(classes_sorted, '', 0)
- self._out += pcc
- elif ctype == 'function':
- assert (isinstance(i, FunctionInfo) for i in cmembers)
- cssclass = ' class="offsanchor"' if DO_CSS_CLASSES else ''
- self._out += (f'' +
- cname + '
\n'
- '\n')
- funcs = cast(list[FunctionInfo], cmembers)
- funcs.sort(key=lambda x: x.name.lower())
- for fnc in funcs:
- self._out += (' - ' +
- fnc.name + '()
\n')
- self._out += '
\n'
- else:
- raise Exception('invalid ctype')
-
- def _filter_docs(self,
- docs: str,
- filter_type: str,
- ignore_links: list[str] = None) -> str:
- get_category_href_func, indent = _filter_type_settings(filter_type)
- docs = docs.replace('>', '>')
- docs = docs.replace('<', '<')
-
- docs_lines = docs.splitlines()
-
- # Make sure empty lines are actually empty (so we can search for
- # '\n\n' and not get thrown off by something like '\n \n').
- for i, line in enumerate(docs_lines):
- if line.strip() == '':
- docs_lines[i] = ''
-
- # If a line starts with 'Category:', make it a link to that category.
- for i, line in enumerate(docs_lines):
- if line.lower().strip().startswith(CATEGORY_STRING.lower()):
- if get_category_href_func is None:
- raise Exception('cant do category for filter_type ' +
- filter_type)
- cat = line.strip()[len(CATEGORY_STRING):].strip()
- docs_lines[i] = (CATEGORY_STRING + ' ' + cat +
- '')
- docs = '\n'.join(docs_lines)
- docs = _split_into_paragraphs(docs, filter_type, indent)
- docs = self._add_index_links(docs, ignore_links)
- return docs
-
- def run(self, outfilename: str) -> None:
- """Generate docs from within the game."""
- import ba
-
- self._gather_funcs(ba)
- self._process_classes(ba)
-
- # Start with our list of classes and functions.
- app = ba.app
- self._out += (f'last updated for Ballistica version '
- f'{app.version} build {app.build_number}
\n')
- self._out += (
- 'This page documents the Python classes'
- ' and functions in the \'ba\' module,\n'
- ' which are the ones most relevant to modding in Ballistica.'
- ' If you come across something you feel'
- ' should be included here or could'
- ' be better explained, please '
- ''
- 'let me know. Happy modding!
\n')
- self._out += '
\n'
- self._out += 'Table of Contents
\n'
-
- self._create_index()
-
- # Build a sorted list of class categories.
- c_categories: dict[str, list[Union[ClassInfo, FunctionInfo]]] = {}
- self._classes.sort(key=lambda x: x.name.lower())
- for cls in self._classes:
- assert cls.category is not None
- category = cls.category
- if category not in c_categories:
- c_categories[category] = []
- c_categories[category].append(cls)
-
- self._merged_categories = [(cname, 'class', cval)
- for cname, cval in c_categories.items()]
-
- # Build sorted function category list.
- f_categories: dict[str, list[FunctionInfo]] = {}
- for fnc in self._functions:
- if fnc.category is not None:
- category = fnc.category
- else:
- category = 'Misc'
- if category not in f_categories:
- f_categories[category] = []
- f_categories[category].append(fnc)
-
- self._merged_categories += [(cname, 'function',
- cast(list[Union[ClassInfo, FunctionInfo]],
- cval))
- for cname, cval in f_categories.items()]
-
- def sort_func(entry: tuple[str, str, Any]) -> str:
- name = entry[0].lower()
-
- # Sort a few recognized categories somewhat manually.
- overrides = {
- 'gameplay classes': 'aaaa',
- 'gameplay functions': 'aaab',
- 'general utility classes': 'aaac',
- 'general utility functions': 'aaad',
- 'asset classes': 'aaae',
- 'asset functions': 'aaaf',
- 'message classes': 'aaag',
- 'app classes': 'aaah',
- 'app functions': 'aaai',
- 'user interface classes': 'aaaj',
- 'user interface functions': 'aaak',
- }
- return overrides.get(name, name)
-
- self._merged_categories.sort(key=sort_func)
-
- # Write out our category listings.
- self._write_category_list()
- self._write_classes()
-
- # Now write docs for each function.
- for fnc in self._functions:
- self._out += '
\n'
- cssclass = ' class="offsanchor"' if DO_CSS_CLASSES else ''
- self._out += (f'' + fnc.name +
- '()\n')
- if fnc.docs is not None:
- self._out += self._filter_docs(fnc.docs, 'function')
-
- # If we've hit any errors along the way, complain.
- if self._errors:
- max_displayed = 10
- print(
- len(self._errors), 'ISSUES FOUND GENERATING DOCS:\n' +
- '\n'.join(self._errors[:max_displayed]))
- clipped = max(0, len(self._errors) - max_displayed)
- if clipped:
- print(f'(and {clipped} more)')
- raise Exception(
- str(len(self._errors)) + ' docs generation issues.')
-
- with open(outfilename, 'w', encoding='utf-8') as outfile:
- outfile.write(self._out)
-
- print(f"Generated docs file: '{Clr.BLU}{outfilename}.{Clr.RST}'")
-
- ba.quit()
-
-
def generate(projroot: str) -> None:
"""Main entry point."""
- toolsdir = os.path.abspath(os.path.join(projroot, 'tools'))
+ from batools.version import get_current_version
+ import pdoc
# Make sure we're running from the dir above this script.
os.chdir(projroot)
- outfilename = os.path.abspath('build/docs.html')
+ templatesdir = (Path(projroot) / 'assets' / 'src' / 'pdoc' /
+ 'templates').absolute()
+ pythondir = (Path(projroot) / 'assets' / 'src' / 'ba_data' /
+ 'python').absolute()
+ outdirname = (Path(projroot) / 'build' / 'docs_html').absolute()
+ sys.path.append(str(pythondir))
- # Let's build the cmake version; no sandboxing issues to contend
- # with there. Also going with the headless build; will need to revisit
- # if there's ever any functionality not available in that build.
- subprocess.run(['make', 'cmake-server-build'], check=True)
-
- # Launch ballisticacore and exec ourself from within it.
- print('Launching ballisticacore to generate docs...')
+ version, build_number = get_current_version()
try:
- subprocess.run(
- [
- './ballisticacore',
- '-exec',
- f'try:\n'
- f' import sys\n'
- f' import ba\n'
- f' sys.path.append("{toolsdir}")\n'
- f' import batools.docs\n'
- f' batools.docs.Generator().run("{outfilename}")\n'
- f' ba.quit()\n'
- f'except Exception:\n'
- f' import sys\n'
- f' import traceback\n'
- f' print("ERROR GENERATING DOCS")\n'
- f' traceback.print_exc()\n'
- f' sys.exit(255)\n',
- ],
- cwd='build/cmake/server-debug/dist',
- check=True,
- )
- except Exception as exc2:
- # Keep our error simple here; we want focus to be on what went
- # wrong withing BallisticaCore.
- raise CleanError('BallisticaCore docs generation failed.') from exc2
+ os.environ['BA_DOCS_GENERATION'] = '1'
+ pdoc.render.env.globals['ba_version'] = version
+ pdoc.render.env.globals['ba_build'] = build_number
+ pdoc.render.configure(search=True,
+ show_source=True,
+ template_directory=templatesdir)
+ pdoc.pdoc('ba', 'bastd', output_directory=outdirname)
+ except Exception as exc:
+ import traceback
+ traceback.print_exc()
+ raise CleanError('Docs generation failed') from exc
- print('Docs generation complete.')
+ print(f'{Clr.GRN}Docs generation complete.{Clr.RST}')
diff --git a/tools/batools/dummymodule.py b/tools/batools/dummymodule.py
index 786e2fe1..051103af 100755
--- a/tools/batools/dummymodule.py
+++ b/tools/batools/dummymodule.py
@@ -21,7 +21,7 @@ from efrotools import get_files_hash
if TYPE_CHECKING:
from types import ModuleType
- from typing import Sequence, Any
+ from typing import Sequence, Any, Optional
from batools.docs import AttributeInfo
@@ -252,7 +252,8 @@ def _writefuncs(parent: Any, funcnames: Sequence[str], indent: int,
f'unknown returns value: {returns} for {funcname}')
returnspc = indstr + ' '
returnstr = ('\n' + returnspc).join(returnstr.strip().splitlines())
- docstr_out = _formatdoc(docstr, indent + 4)
+ docstr_out = _formatdoc(_filterdoc(docstr, funcname=funcname),
+ indent + 4)
out += spcstr + defsline + docstr_out + f'{returnspc}{returnstr}\n'
return out
@@ -470,18 +471,58 @@ def _special_class_cases(classname: str) -> str:
return out
-def _formatdoc(docstr: str, indent: int) -> str:
+def _filterdoc(docstr: str, funcname: Optional[str] = None) -> str:
+ docslines = docstr.splitlines()
+
+ if (funcname and docslines and docslines[0]
+ and docslines[0].startswith(funcname)):
+ # Remove this signature from python docstring
+ # as not to repeat ourselves.
+ _, docstr = docstr.split('\n\n', maxsplit=1)
+ docslines = docstr.splitlines()
+
+ # Assuming that each line between 'Attributes:' and '\n\n' belongs to
+ # attrs descriptions.
+ empty_lines_count = 0
+ attributes_line: Optional[int] = None
+ attrs_definitions_last_line: Optional[int] = None
+ for i, line in enumerate(docslines):
+ if line.strip() in ['Attrs:', 'Attributes:']:
+ if attributes_line is not None:
+ raise Exception("Multiple 'Attributes:' lines found")
+ attributes_line = i
+ if not line.strip():
+ empty_lines_count += 1
+ else:
+ empty_lines_count = 0
+ if empty_lines_count >= 2 and attributes_line is not None:
+ # It seems attribute definitions ended.
+ attrs_definitions_last_line = i
+ break
+ if attrs_definitions_last_line is None:
+ attrs_definitions_last_line = len(docslines) - 1
+
+ return '\n'.join(docslines[:attributes_line] +
+ docslines[attrs_definitions_last_line + 1:])
+
+
+def _formatdoc(docstr: str,
+ indent: int,
+ no_end_newline: bool = False,
+ inner_indent: int = 0) -> str:
out = ''
indentstr = indent * ' '
+ inner_indent_str = inner_indent * ' '
docslines = docstr.splitlines()
+
if len(docslines) == 1:
out += '\n' + indentstr + '"""' + docslines[0] + '"""\n'
else:
for i, line in enumerate(docslines):
if i != 0 and line != '':
- docslines[i] = indentstr + line
- out += ('\n' + indentstr + '"""' + '\n'.join(docslines) + '\n' +
- indentstr + '"""\n')
+ docslines[i] = indentstr + inner_indent_str + line
+ out += ('\n' + indentstr + '"""' + '\n'.join(docslines) +
+ ('' if no_end_newline else '\n' + indentstr) + '"""\n')
return out
@@ -503,7 +544,8 @@ def _writeclasses(module: ModuleType, classnames: Sequence[str]) -> str:
out += f'class {classname}:\n'
docstr = cls.__doc__
- out += _formatdoc(docstr, 4)
+ # classname is constructor name
+ out += _formatdoc(_filterdoc(docstr, funcname=classname), 4)
# Create a public constructor if it has one.
# If the first docs line appears to be a function signature
@@ -537,6 +579,12 @@ def _writeclasses(module: ModuleType, classnames: Sequence[str]) -> str:
for attr in attrs:
if attr.attr_type is not None:
out += f' {attr.name}: {attr.attr_type}\n'
+ if attr.docs:
+ out += _formatdoc(_filterdoc(attr.docs),
+ indent=4,
+ inner_indent=3,
+ no_end_newline=True)
+ out += '\n'
else:
raise Exception(f'Found untyped attr in'
f' {classname} docs: {attr.name}')
@@ -581,7 +629,8 @@ def generate(sources_hash: str, outfilename: str) -> None:
# Ignore _ba.app.
continue
else:
- raise Exception(f'found unknown obj {entry}')
+ raise Exception(
+ f'found unknown obj {entry}, {getattr(module, entry)}')
funcnames.sort()
classnames.sort()
out = (get_public_license('python')