Built the SCons Tools documentation and README.md

site_scons/site_tools/README.md

@@ -0,0 +1,11 @@
+# FSAE Concordia SCons Tools
+
+**This section of the codebase houses all additional internal/external tools for SCons**
+
+| Tool Name | Description | File location | Notes |
+| --- | --- | --- | ---|
+| ARM Toolchain | Adds support for the ARM Toolchain | site_scons/site_tools/arm-none-eabi.py | |
+| Chip Confirguration | Adds the ability to configure chips from config file | site_scons/site_tools/chip_config.py | |
+| Doxygen | Adds doxygen support | site_scons/site_tools/dox.py | |
+| OpenOCD | Adds openocd support | site_scons/site_tools/openocd.py | |
+| ST-Flash | Adds ST-Link flashing support | site_scons/site_tools/st-flash.py | |

site_scons/site_tools/arm-none-eabi.py

@@ -1,9 +1,27 @@
+##
+# @file arm-none-eabi.py
+# @brief  Adds support for ARM Toolchain
+# @author Ricky Lopez
+# @version 0.1
+# @date 2022-08-27
+
 from os.path import splitext
 from SCons.Script import *
 
-TOOL_PATH = Dir("/opt/toolchains/gcc-arm-none-eabi/bin/")
+TOOL_PATH = Dir("/opt/toolchains/gcc-arm-none-eabi/bin/") # @brief Absolute path of binaries when inside container
 
 
+##
+# @brief  Compiles the targets with signature
+#
+# @note Not to be called directly
+#
+# @param target Target output file
+# @param source Sources to be used
+# @param env Environment to be worked on
+# @param for_signature Signature given to Target
+#
+# @retval   Returns the SCons action
 def _program(target, source, env, for_signature):
     return SCons.Action.Action(
         [
@@ -13,20 +31,46 @@ def _program(target, source, env, for_signature):
     )
 
 
+##
+# @brief Appends the Binary and Map file to the target and returns with source
+#
+# @note Not to be called directly
+
+# @param target Target to work on
+# @param source Source to work from
+# @param env Environment being worked on
+#
+# @retval   [target, source]
 def _bin_emitter(target, source, env):
     bin_file = "build/" + splitext(target[0].name)[0] + ".bin"
     map_file = "build/" + splitext(target[0].name)[0] + ".map"
     target.append([bin_file, map_file])
     return target, source
 
 
+##
+# @brief Adds ARM GDB support 
+#
+# @note Not to be called directly
+#
+# @param env Environment to work on
+# @param elf_file ELF file
+# @param args args to be passed to GDB
+#
+# @retval   Return execution of SCons GDB
 def _gdb(env, elf_file, *args):
     args = " ".join(args)
     fn = "phony.file" + str(len(args))
     env.Pseudo(fn)
     return env.gdb(source=elf_file, target=fn, args=args)
 
 
+##
+# @brief  Generates the SCons tools in the environment
+#
+# @param env Environment to be worked on
+#
+# @retval   None
 def generate(env):
     SCons.Tool.Tool("cc")(env)
     SCons.Tool.Tool("ar")(env)
@@ -63,5 +107,11 @@ def tool_path(tool: str) -> str:
     env.AddMethod(_gdb, "launch_gdb")
 
 
+##
+# @brief  Shows this module exists
+#
+# @note Included for forward compatibility
+#
+# @retval True 
 def exists():
     return True

site_scons/site_tools/chip_config.py

@@ -1,10 +1,23 @@
+##
+# @file chip_config.py
+# @brief  Adds chip configuration support into SCons
+# @author Ricky Lopez
+# @version 0.1
+# @date 2022-08-27
+
 from yaml import load, Loader
 
 from SCons.Script import *
 
 from os.path import join
 
 
+##
+# @brief  Generates additional defines to be included from configuration file
+#
+# @param chip_config Configuration file
+#
+# @retval   Additional defines to be added
 def generate_defines(chip_config):
     defines = []
     for key, val in chip_config["defines"].items():
@@ -16,6 +29,15 @@ def generate_defines(chip_config):
     return defines
 
 
+##
+# @brief  Configures chip for the build system
+#
+# @note Not to be called directly
+#
+# @param env Environment to be worked on
+# @param config_file Chip configuration to be used
+#
+# @retval   Dictionary of lists with different configurations to be appeneded to build system
 def _configure_chip(env, config_file):
     REPO_ROOT_DIR = env["REPO_ROOT_DIR"]
     KNOWN_CHIPS_FILE = REPO_ROOT_DIR.File("site_scons/chips.yaml")
@@ -149,9 +171,19 @@ def _configure_chip(env, config_file):
     return ret
 
 
+##
+# @brief  Generate configuration support for SCons
+#
+# @param env Environment to be worked on
+#
+# @retval   None
 def generate(env):
     env.AddMethod(_configure_chip, "ChipConfig")
 
 
+##
+# @brief Shows module exists 
+#
+# @retval   True
 def exists():
     return True

site_scons/site_tools/dox.py

@@ -1,12 +1,32 @@
+##
+# @file dox.py
+# @brief  SCons python tool for Doxygen integration
+# @author Joshua Lafleur ([email protected])
+# @version 0.1
+# @date 2022-08-27
+
 from SCons.Script import *
 
 
+##
+# @brief  Generates the helper actions in SCons
+#
+# @param env SCons environment to work on
+#
+# @retval   None
 def generate(env):
+    # @brief Adds the bash command as a builder to the environment
     env['BUILDERS']['dox'] = SCons.Builder.Builder(
         action = f"doxygen -g $SOURCE"
     )
 
 
+##
+# @brief  Shows that this module exists
+#
+# @note     Included for forward compatibility
+#
+# @retval   True
 def exists():
     return True
 

site_scons/site_tools/doxygen.conf

@@ -491,7 +491,7 @@ EXTRACT_ALL            = YES
 # be included in the documentation.
 # The default value is: NO.
 
-EXTRACT_PRIVATE        = NO
+EXTRACT_PRIVATE        = YES
 
 # If the EXTRACT_PRIV_VIRTUAL tag is set to YES, documented private virtual
 # methods of a class will be included in the documentation.
@@ -864,7 +864,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = site_scons/site_tools
+INPUT                  = README.md site_scons/site_tools
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1061,7 +1061,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE =
+USE_MDFILE_AS_MAINPAGE = site_scons/site_tools/README.md 
 
 #---------------------------------------------------------------------------
 # Configuration options related to source browsing

site_scons/site_tools/openocd.py

@@ -1,8 +1,26 @@
+##
+# @file openocd.py
+# @brief  Adds OpenOCD support to SCons
+# @author Ricky Lopez
+# @version 0.1
+# @date 2022-08-27
+
+
 from SCons.Script import *
 
 OPENOCD_DIR = Dir("#embedded/openocd")
 
 
+##
+# @brief Starts the OpenOCD server for interface and board 
+#
+# @note Not to be called directly
+#
+# @param env Environment to be worked on
+# @param interface Interface to use
+# @param board Board to use
+#
+# @retval   Returns execution of server
 def _start_server(env, interface, board):
 
     interface = OPENOCD_DIR.Dir("interface").File(interface + ".cfg")
@@ -19,6 +37,16 @@ def _start_server(env, interface, board):
     return ret
 
 
+##
+# @brief  Creates piped bash command to get server
+#
+# @note Not to be called directly
+#
+# @param env Environment to be worked on
+# @param interface Interface to use
+# @param board Board to use
+#
+# @retval   Command to be executed
 def _get_openocd_cmd(env, interface, board):
 
     interface = OPENOCD_DIR.Dir("interface").File(interface + ".cfg")
@@ -37,6 +65,12 @@ def _get_openocd_cmd(env, interface, board):
     return ret
 
 
+##
+# @brief  Generates SCons support for OpenOCD
+#
+# @param env Environment to be worked on
+#
+# @retval   None
 def generate(env):
     env.AddMethod(_start_server, "openocd_srv")
     env.AddMethod(_get_openocd_cmd, "openocd_cmd")
@@ -46,5 +80,9 @@ def generate(env):
     )
 
 
+##
+# @brief  Shows module exists
+#
+# @retval   True
 def exists():
     return True

site_scons/site_tools/st-flash.py

@@ -1,3 +1,11 @@
+##
+# @file st-flash.py
+# @brief  Adds ST-Flash support to Scons
+# @author Ricky Lopez
+# @version 0.1
+# @date 2022-08-27
+
+
 from SCons.Script import *
 
 
@@ -6,6 +14,12 @@
 #     return env.flash_chip(bin_file)
 
 
+##
+# @brief  Generates SCons support for ST-Flash
+#
+# @param env Environment to be worked on
+#
+# @retval   None
 def generate(env):
     # env.AddMethod(_flash_chip, "flash")
 
@@ -16,5 +30,9 @@ def generate(env):
     )
 
 
+##
+# @brief  Shows module exists
+#
+# @retval   True
 def exists():
     return True