Update python scripts with docs

build_scripts/win/build.py

@@ -1,9 +1,58 @@
+"""
+Build script to compile OpenVR Advanced Settings on Windows.
+
+The entire purpose of the script is to locate the correct install locations
+for seven different applications:
+
+1. Qt Framework, used for compiling.
+2. Visual Studio, used for setting up the variables needed to compile with Qt.
+3. jom.exe, a part of Qt, basically a multi core nmake.
+4. 7zip. Used for creating the portable versions of the app.
+5. NSIS. Used for creating the installer versions of the app.
+6. LLVM. Used for clang-format and clang-cl.
+7. Qmake, a part of Qt, used for creating the makefiles.
+
+The script does error checking on environmental variables before outputting
+a simple Windows batch file that will be called by other batch scripts.
+
+The reason that a batch file is created and run outside of python is that if 
+you don't do it like that, you have these options
+
+1) Run applications one by one in python.
+
+    This is not viable because the build() function requires that a batch file
+    be run to set up environmental variables for QMAKE and nmake, and all environmental
+    variables and settings are lost between sessions.
+
+2) Batch all applications together and run them in python.
+
+    This is still a viable way of doing things, but creating an actual file
+    makes debugging and experimentation a lot easier by less experienced people.
+    Furthermore the stdout and stderr output wouldn't be real time without adding
+    unnecessary complexity.
+
+3) Write the entire thing in another language (like Powershell).
+
+    This was tried and even though Powershell has decent stdlib functionality like 
+    testing paths and replacing chars in strings, it is still lacking in some areas
+    like actually running .exe files without resorting to weird tricks and cmd line hacks.
+    In addition, Powershell has some weird tendencies compared to other "real"
+    programming languages that would add unnecessary complexity.
+
+Writing this script in pure Windows batch file language is definitely possible,
+but the large amounts of replication and low amounts of abstraction possibilities
+will make development and extension a chore.
+"""
+
 import os
 from sys import argv
 import inspect
 from common import *
 
 def package():
+    """
+    Runs 7zip and NSIS to create portable and installer versions.
+    """
     set_current_activity("PACKAGE")
     set_dirs()
 
@@ -16,6 +65,7 @@ def package():
     ZIP_NAME = "AdvancedSettings-" + VERSION_STRING + ".7z"
 
     add_line_to_run_bat_file("@ECHO Starting 7zip:")
+    # -t7z means to output a 7zip file.
     add_line_to_run_bat_file('"' + ZIP_LOC + '"' + " a -t7z " + get_project_dir() + "\\bin\\win64\\" + ZIP_NAME + " " + get_deploy_dir() + "\\*")
     add_error_handling_line_to_bat_file()
     add_line_to_run_bat_file("@ECHO 7zip done.")
@@ -33,6 +83,9 @@ def package():
 
 
 def deploy():
+    """
+    Runs windeployqt and copies necessary files.
+    """
     set_current_activity("DEPLOY")
     set_dirs()
 
@@ -89,6 +142,12 @@ def deploy():
     
 
 def build():
+    """
+    Runs:
+        'vcvarsall.bat', a Visual Studio file to set up the environment for QMAKE.
+        QMAKE, creates the makefiles.
+        jom/nmake, builds the makefiles.
+    """
     set_current_activity("BUILD")
     set_dirs()