Move pidtune js to extension (#1918)

Co-authored-by: Vasista Vovveti <[email protected]>

.gitignore

@@ -101,6 +101,3 @@ venv/
 # If by any chance some Inspector temp files or the report passed through
 *.tmp
 report.md
-
-# Temp JS build
-source/_static/js/pid-tune.js

source/_extensions/controls_js_sim/__init__.py

@@ -0,0 +1,101 @@
+from pathlib import Path
+from typing import Any, Dict
+
+import os, glob
+from jsmin import jsmin
+from sphinx.application import Sphinx
+
+# Handle custom javascript
+# Groups, sorts, merges, and minifies the JS files assocated with
+# the controls documentation
+
+debugJS = False  # flip to true to make the output js more readable
+
+# Include Order - specifies which folders to pull in and in which order
+# This must be kept in sync with the dependencies within the javascript itself
+# Ideally, in the future, the javascript should be allowed to include other .js files
+# but for now, we'll just make one mega file
+FOLDER_INCS = [
+    "fastchart",
+    "utils",
+    "base",
+    "plant",
+    "visualization",
+    "sim",
+    ".",
+]
+
+
+def mergeAndMinify(out_folder):
+
+    if not os.path.isdir(out_folder):
+        os.makedirs(out_folder)
+
+    outputFile = os.path.join(out_folder, "pid-tune.js")
+
+    with open(outputFile, "w") as outf:
+        for folder in FOLDER_INCS:
+
+            jsRoot = os.path.dirname(__file__)
+            # find all js files in the specific folder
+            inFileNames = glob.glob(os.path.join(jsRoot, folder, "*.js"))
+
+            # sort file names alphabetically
+            # this allows a within-folder sort by number prefix if needed.
+            inFileNames.sort()
+
+            for inFileName in inFileNames:
+
+                with open(inFileName, "r") as inf:
+                    if not debugJS:
+                        # Minify each file independently - again, low bar solution for now
+                        minified = jsmin(inf.read())
+                        outf.write(minified)
+                        outf.write("\n")
+                    else:
+                        # Verbose, no minify, and add debug markers.
+                        outf.write("\n\n\n")
+                        outf.write(
+                            "//*******************************************************\n"
+                        )
+                        outf.write(
+                            "//*******************************************************\n"
+                        )
+                        outf.write("//**    {}\n".format(inFileName))
+                        outf.write(
+                            "//*******************************************************\n"
+                        )
+                        outf.write(
+                            "//*******************************************************\n"
+                        )
+                        outf.write("\n")
+                        outf.write(inf.read())
+                        outf.write("\n")
+
+    return outputFile
+
+
+def setup(app: Sphinx) -> Dict[str, Any]:
+
+    print("Generating and adding controls javascript...")
+
+    # Perform controls js setup
+    static_dir = Path(__file__).parent / "_static"
+
+    # everything written to this new static folder in this `setup` will be copied to the build static folder as is
+    app.connect(
+        "builder-inited",
+        (lambda app: app.config.html_static_path.append(static_dir.as_posix())),
+    )
+
+    # Generate merged/minified PID tuning source
+    mergeAndMinify(static_dir)
+
+    # Add interactive PID tuning
+    app.add_js_file("pid-tune.js")
+    app.add_css_file("css/pid-tune.css")
+
+    return {
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

source/_extensions/controls_js_sim/_static/.gitignore

@@ -0,0 +1,2 @@
+# Auto-Generated files
+pid-tune.js

source/conf.py

@@ -14,11 +14,9 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
+from pathlib import Path
 import sys
 import os
-import glob
-from jsmin import jsmin
-
 
 sys.path.append(os.path.abspath("."))
 sys.path.append(os.path.abspath("./frc-docs/source"))
@@ -66,6 +64,7 @@
     "_extensions.post_process",
     "_extensions.rtd_patch",
     "_extensions.localization",
+    "_extensions.controls_js_sim",
 ]
 
 extensions += local_extensions
@@ -221,57 +220,6 @@
     ("warning-is-error", True),
 ]
 
-# Handle custom javascript
-# We generally want to group, merge, and minify the js files
-
-if "BASEDIR" in globals():
-    # allow an alternate basedir if set into globals by another script
-    js_build_dir = BASEDIR
-else:
-    # otherwise, just use this file's directory
-    js_build_dir = os.path.dirname(__file__)
-
-js_pid_src_path = os.path.join(js_build_dir, "_static/js/pid-tune/*.js")
-js_pid_output_file = os.path.join(js_build_dir, "_static/js/pid-tune.js")
-
-debugJS = False  # flip to true to make the output js more readable
-
-
-def mergeAndMinify(sourceDir, outputFile):
-    with open(outputFile, "w") as outf:
-        inFileNames = glob.glob(sourceDir)
-        # It is not trivial to figure out which order to include the javascript
-        # source files into the final minified file.
-        # Current low-bar solution - assume file names are prefixed with numbers,
-        # such that a sort puts them in the right order.
-        inFileNames.sort()
-        for inFileName in inFileNames:
-            with open(inFileName, "r") as inf:
-                if not debugJS:
-                    # Minify each file independently - again, low bar solution for now
-                    minified = jsmin(inf.read())
-                    outf.write(minified)
-                    outf.write("\n")
-                else:
-                    # Verbose, no minify
-                    outf.write("\n\n\n")
-                    outf.write(
-                        "//*******************************************************\n"
-                    )
-                    outf.write(
-                        "//*******************************************************\n"
-                    )
-                    outf.write("//**    {}\n".format(inFileName))
-                    outf.write(
-                        "//*******************************************************\n"
-                    )
-                    outf.write(
-                        "//*******************************************************\n"
-                    )
-                    outf.write("\n")
-                    outf.write(inf.read())
-                    outf.write("\n")
-
 
 def setup(app):
     app.add_css_file("css/frc-rtd.css")
@@ -294,13 +242,6 @@ def setup(app):
     # Add 2014 archive link to rtd versions menu
     app.add_js_file("js/version-2014.js")
 
-    # Generate merged/minified PID tuning source
-    mergeAndMinify(js_pid_src_path, js_pid_output_file)
-
-    # Add interactive PID tuning
-    app.add_js_file("js/pid-tune.js")
-    app.add_css_file("css/pid-tune.css")
-
 
 # -- Options for latex generation --------------------------------------------
 
@@ -312,16 +253,16 @@ def setup(app):
 
 latex_elements = {
     "fontpkg": r"""
-	\setmainfont{DejaVu Serif}
-	\setsansfont{DejaVu Sans}
-	\setmonofont{DejaVu Sans Mono}""",
+    \setmainfont{DejaVu Serif}
+    \setsansfont{DejaVu Sans}
+    \setmonofont{DejaVu Sans Mono}""",
     "preamble": r"""
-	\usepackage[titles]{tocloft}
-	\cftsetpnumwidth {1.25cm}\cftsetrmarg{1.5cm}
-	\setlength{\cftchapnumwidth}{0.75cm}
-	\setlength{\cftsecindent}{\cftchapnumwidth}
-	\setlength{\cftsecnumwidth}{1.25cm}
-	""",
+    \usepackage[titles]{tocloft}
+    \cftsetpnumwidth {1.25cm}\cftsetrmarg{1.5cm}
+    \setlength{\cftchapnumwidth}{0.75cm}
+    \setlength{\cftsecindent}{\cftchapnumwidth}
+    \setlength{\cftsecnumwidth}{1.25cm}
+    """,
     "fncychap": r"\usepackage[Bjornstrup]{fncychap}",
     "printindex": r"\footnotesize\raggedright\printindex",
 }