doc: _extensions: support snippets option

Support `zephyr-app-commands` being provided with a `snippets`,
option, to specify building with the listed snippets.

Signed-off-by: Jordan Yates <jordan.yates@data61.csiro.au>

doc/_extensions/zephyr/application.py

@@ -69,6 +69,10 @@ class ZephyrAppCommandsDirective(Directive):
     \:build-args:
       if set, additional arguments to the build invocation
 
+    \:snippets:
+      if set, indicates the application should be compiled with the listed snippets.
+      Multiple snippets can be provided in a comma separated list.
+
     \:build-dir:
       if set, the application build directory will *APPEND* this
       (relative, Unix-separated) path to the standard build directory. This is
@@ -116,6 +120,7 @@ class ZephyrAppCommandsDirective(Directive):
         'conf': directives.unchanged,
         'gen-args': directives.unchanged,
         'build-args': directives.unchanged,
+        'snippets': directives.unchanged,
         'build-dir': directives.unchanged,
         'build-dir-fmt': directives.unchanged,
         'goals': directives.unchanged_required,
@@ -147,6 +152,7 @@ class ZephyrAppCommandsDirective(Directive):
         conf = self.options.get('conf', None)
         gen_args = self.options.get('gen-args', None)
         build_args = self.options.get('build-args', None)
+        snippets = self.options.get('snippets', None)
         build_dir_append = self.options.get('build-dir', '').strip('/')
         build_dir_fmt = self.options.get('build-dir-fmt', None)
         goals = self.options.get('goals').split()
@@ -190,6 +196,10 @@ class ZephyrAppCommandsDirective(Directive):
         # Create tools array
         tools = [tool] if tool != "all" else [v for v in self.TOOLS
                                                 if v != 'all']
+
+        # Create snippet array
+        snippet_list = snippets.split(',') if snippets is not None else None
+
         # Build the command content as a list, then convert to string.
         content = []
         tool_comment = None
@@ -206,6 +216,7 @@ class ZephyrAppCommandsDirective(Directive):
             'conf': conf,
             'gen_args': gen_args,
             'build_args': build_args,
+            'snippets': snippet_list,
             'build_dir': build_dir,
             'build_dir_fmt': build_dir_fmt,
             'goals': goals,
@@ -263,6 +274,7 @@ class ZephyrAppCommandsDirective(Directive):
         build_dir = kwargs['build_dir']
         build_dir_fmt = kwargs['build_dir_fmt']
         compact = kwargs['compact']
+        snippets = kwargs['snippets']
         west_args = kwargs['west_args']
         flash_args = kwargs['flash_args']
         kwargs['board'] = None
@@ -272,6 +284,7 @@ class ZephyrAppCommandsDirective(Directive):
         cmake_args = ' --{}'.format(cmake_args) if cmake_args != '' else ''
         west_args = ' {}'.format(west_args) if west_args else ''
         flash_args = ' {}'.format(flash_args) if flash_args else ''
+        snippet_args = ''.join(f' -S {s}' for s in snippets) if snippets else ''
         # ignore zephyr_app since west needs to run within
         # the installation. Instead rely on relative path.
         src = ' {}'.format(app) if app and not cd_into else ''
@@ -301,8 +314,8 @@ class ZephyrAppCommandsDirective(Directive):
         # defaulting to west.
         #
         # For now, this keeps the resulting commands working.
-        content.append('west build -b {}{}{}{}{}'.
+        content.append('west build -b {}{}{}{}{}{}'.
-                       format(board, west_args, build_dst, src, cmake_args))
+                       format(board, west_args, snippet_args, build_dst, src, cmake_args))
 
         # If we're signing, we want to do that next, so that flashing
         # etc. commands can use the signed file which must be created
@@ -397,6 +410,7 @@ class ZephyrAppCommandsDirective(Directive):
         in_tree = kwargs['in_tree']
         build_dir = kwargs['build_dir']
         build_args = kwargs['build_args']
+        snippets = kwargs['snippets']
         skip_config = kwargs['skip_config']
         goals = kwargs['goals']
         compact = kwargs['compact']
@@ -422,6 +436,7 @@ class ZephyrAppCommandsDirective(Directive):
         # Now generate the actual cmake and make/ninja commands
         gen_arg = ' -GNinja' if generator == 'ninja' else ''
         build_args = ' {}'.format(build_args) if build_args else ''
+        snippet_args = ' -DSNIPPET="{}"'.format(';'.join(snippets)) if snippets else ''
         cmake_args = self._cmake_args(**kwargs)
 
         if not compact:
@@ -433,8 +448,8 @@ class ZephyrAppCommandsDirective(Directive):
                 content.append('# Use cmake to configure a {}-based build' \
                                'system:'.format(generator.capitalize()))  # noqa: E501
 
-        content.append('cmake{}{}{}{}'.format(cmake_build_dir, gen_arg,
+        content.append('cmake{}{}{}{}{}'.format(cmake_build_dir, gen_arg,
-                                              cmake_args, source_dir))
+                                              cmake_args, snippet_args, source_dir))
         if not compact:
             content.extend(['',
                             '# Now run the build tool on the generated build system:'])