Exposing documentation generation functionality

Makefile

@@ -1021,5 +1021,12 @@ _windows-wsl-rebuild:
    $(VISUAL_STUDIO_VERSION)
 	@tools/pcommand echo BLU BLD Built build/windows/BallisticaCore$(WINPRJ).exe.
 
+# Generate docs.
+docs:
+	@tools/pcommand echo BLU GENERATING DOCS HTML...
+	@mkdir -p ${BUILD_DIR}
+	@tools/pcommand gendocs
+
 # Tell make which of these targets don't represent files.
-.PHONY: _cmake-simple-ci-server-build _windows-wsl-build _windows-wsl-rebuild
+.PHONY: _cmake-simple-ci-server-build _windows-wsl-build _windows-wsl-rebuild \
+      docs

docs/ba_module.md

@@ -1,5 +1,5 @@
 <!-- THIS FILE IS AUTO GENERATED; DO NOT EDIT BY HAND -->
-<h4><em>last updated on 2021-06-09 for Ballistica version 1.6.4 build 20375</em></h4>
+<h4><em>last updated on 2021-06-10 for Ballistica version 1.6.4 build 20377</em></h4>
 <p>This page documents the Python classes and functions in the 'ba' module,
  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 <a href="mailto:support@froemling.net">let me know</a>. Happy modding!</p>
 <hr>

tools/batools/build.py

@@ -784,7 +784,7 @@ def update_docs_md(check: bool) -> None:
     # We store the hash in a separate file that only exists on private
     # so public isn't full of constant hash change commits.
     # (don't care so much on private)
-    docs_hash_path = 'docs/ba_module_hash'
+    docs_hash_path = '.cache/ba_module_hash'
 
     # Generate a hash from all c/c++ sources under the python subdir
     # as well as all python scripts.
@@ -802,13 +802,18 @@ def update_docs_md(check: bool) -> None:
                 if any(fname.endswith(ext) for ext in exts):
                     pysources.append(os.path.join(root, fname))
     pysources.sort()
+    storedhash: Optional[str]
     curhash = get_files_hash(pysources)
 
     # Extract the current embedded hash.
-    with open(docs_hash_path) as infile:
-        storedhash = infile.read()
+    if os.path.exists(docs_hash_path):
+        with open(docs_hash_path) as infile:
+            storedhash = infile.read()
+    else:
+        storedhash = None
 
-    if curhash != storedhash or not os.path.exists(docs_path):
+    if (storedhash is None or curhash != storedhash
+            or not os.path.exists(docs_path)):
         if check:
             raise RuntimeError('Docs markdown is out of date.')
 
@@ -821,6 +826,7 @@ def update_docs_md(check: bool) -> None:
             docs = infile.read()
         docs = ('<!-- THIS FILE IS AUTO GENERATED; DO NOT EDIT BY HAND -->\n'
                 ) + docs
+        os.makedirs(os.path.dirname(docs_path), exist_ok=True)
         with open(docs_path, 'w') as outfile:
             outfile.write(docs)
         with open(docs_hash_path, 'w') as outfile:

tools/batools/pcommand.py

@@ -444,6 +444,12 @@ def warm_start_asset_build() -> None:
             check=True)
 
 
+def gendocs() -> None:
+    """Generate docs html."""
+    import batools.gendocs
+    batools.gendocs.run(projroot=str(PROJROOT))
+
+
 def update_docs_md() -> None:
     """Updates docs markdown files if necessary."""
     import batools.build

tools/batools/updateproject.py

@@ -118,6 +118,10 @@ class Updater:
         # (this will get filtered and be unequal in spinoff projects)
         if 'ballistica' + 'core' == 'ballisticacore':
             self._update_dummy_module()
+
+        # Docs checks/updates will only run if BA_ENABLE_DOCS_UPDATES=1
+        # is set in the environment.
+        if os.environ.get('BA_ENABLE_DOCS_UPDATES') == '1':
             self._update_docs_md()
 
         if self._check:
@@ -175,14 +179,12 @@ class Updater:
         # We need to do this near the end because it may run the cmake build
         # so its success may depend on the cmake build files having already
         # been updated.
-        # (only do this if gendocs is available)
-        if os.path.exists('tools/gendocs.py'):
-            try:
-                subprocess.run(['tools/pcommand', 'update_docs_md'] +
-                               self._checkarglist,
-                               check=True)
-            except Exception as exc:
-                raise CleanError('Error checking/updating docs') from exc
+        try:
+            subprocess.run(['tools/pcommand', 'update_docs_md'] +
+                           self._checkarglist,
+                           check=True)
+        except Exception as exc:
+            raise CleanError('Error checking/updating docs') from exc
 
     def _update_prereqs(self) -> None:
 

tools/pcommand

@@ -33,13 +33,13 @@ from batools.pcommand import (
     python_build_apple, python_build_apple_debug, python_build_android,
     python_build_android_debug, python_android_patch, python_gather,
     python_winprune, capitalize, upper, efrocache_update, efrocache_get,
-    get_modern_make, warm_start_asset_build, update_docs_md, list_pip_reqs,
-    install_pip_reqs, checkenv, ensure_prefab_platform, prefab_run_var,
-    make_prefab, update_makebob, lazybuild, android_archive_unstripped_libs,
-    efro_gradle, stage_assets, update_assets_makefile, update_project,
-    update_cmake_prefab_lib, cmake_prep_dir, gen_binding_code,
-    gen_flat_data_code, wsl_path_to_win, wsl_build_check_win_drive,
-    win_ci_binary_build, genchangelog)
+    get_modern_make, warm_start_asset_build, gendocs, update_docs_md,
+    list_pip_reqs, install_pip_reqs, checkenv, ensure_prefab_platform,
+    prefab_run_var, make_prefab, update_makebob, lazybuild,
+    android_archive_unstripped_libs, efro_gradle, stage_assets,
+    update_assets_makefile, update_project, update_cmake_prefab_lib,
+    cmake_prep_dir, gen_binding_code, gen_flat_data_code, wsl_path_to_win,
+    wsl_build_check_win_drive, win_ci_binary_build, genchangelog)
 # pylint: enable=unused-import
 
 if TYPE_CHECKING: