Improve a bit of documentation, add comments, and update code structure

Author: pyth0n1c

contentctl/actions/initialize.py

@@ -2,8 +2,6 @@
 import shutil
 import os
 import pathlib
-
-from pydantic import RootModel 
 from contentctl.objects.config import test
 from contentctl.output.yml_writer import YmlWriter
 
@@ -17,42 +15,47 @@ def execute(self, config: test) -> None:
 
         YmlWriter.writeYmlFile(str(config.path/'contentctl.yml'), config.model_dump()) 
 
-        if config.bare:
-            #Create the following empty directories:
-            for emptyDir in ['lookups', 'baselines', 'docs', 'reporting', 'investigations', 'deployments', 
-                             'detections/application', 'detections/cloud', 'detections/endpoint', 
-                             'detections/network', 'detections/web', 'data_sources', 'macros', 'stories']:
-                #Throw an error if this directory already exists
-                (config.path/emptyDir).mkdir(exist_ok=False, parents=True)
-            
-            # Copy the contents of the app_template directory
-            source_directory = pathlib.Path(os.path.dirname(__file__))/'../templates/app_template/'
-            target_directory = config.path/'app_template'
-            shutil.copytree(source_directory, target_directory, dirs_exist_ok=False)
 
-        else:
-            #Create the following empty directories:
-            for emptyDir in ['lookups', 'baselines', 'docs', 'reporting', 'investigations']:
-                #Throw an error if this directory already exists
-                (config.path/emptyDir).mkdir(exist_ok=False)
-
+        #Create the following empty directories:
+        for emptyDir in ['lookups', 'baselines', 'data_sources', 'docs', 'reporting', 'investigations', 
+                            'detections/application', 'detections/cloud', 'detections/endpoint', 
+                            'detections/network', 'detections/web', 'macros', 'stories']:
+            #Throw an error if this directory already exists
+            (config.path/emptyDir).mkdir(exist_ok=False, parents=True)
+
+        # If this is not a bare config, then populate
+        # a small amount of content into the directories
+        if not config.bare:
             #copy the contents of all template directories
             for templateDir, targetDir in [
-                ('../templates/app_template/', 'app_template'),
-                ('../templates/deployments/', 'deployments'),
                 ('../templates/detections/', 'detections'),
                 ('../templates/data_sources/', 'data_sources'),
-                ('../templates/macros/','macros'),
+                ('../templates/macros/', 'macros'),
                 ('../templates/stories/', 'stories'),
             ]:
                 source_directory = pathlib.Path(os.path.dirname(__file__))/templateDir
                 target_directory = config.path/targetDir
-                #Throw an exception if the target exists
-                shutil.copytree(source_directory, target_directory, dirs_exist_ok=False)
+                
+                # Do not throw an exception if the directory exists. In fact, it was 
+                # created above when the structure of the app was created.
+                shutil.copytree(source_directory, target_directory, dirs_exist_ok=True)
 
-            # Create a README.md file.  Note that this is the README.md for the repository, not the
-            # one which will actually be packaged into the app. That is located in the app_template folder.
-            shutil.copyfile(pathlib.Path(os.path.dirname(__file__))/'../templates/README.md','README.md')
+        # The contents of app_template must ALWAYS be copied because it contains
+        # several special files.
+        # For now, we also copy the deployments because the ability to create custom
+        # deployment files is limited with built-in functionality.
+        for templateDir, targetDir in [
+            ('../templates/app_template/', 'app_template'),
+            ('../templates/deployments/', 'deployments')
+        ]:
+            source_directory = pathlib.Path(os.path.dirname(__file__))/templateDir
+            target_directory = config.path/targetDir
+            #Throw an exception if the target exists
+            shutil.copytree(source_directory, target_directory, dirs_exist_ok=False)
+
+        # Create a README.md file.  Note that this is the README.md for the repository, not the
+        # one which will actually be packaged into the app. That is located in the app_template folder.
+        shutil.copyfile(pathlib.Path(os.path.dirname(__file__))/'../templates/README.md','README.md')
 
 
         print(f"The app '{config.app.title}' has been initialized. "

contentctl/objects/config.py

@@ -172,7 +172,12 @@ def serialize_path(path: DirectoryPath)->str:
 
 class init(Config_Base):
     model_config = ConfigDict(use_enum_values=True,validate_default=True, arbitrary_types_allowed=True)
-    bare: bool = Field(default=False, description="Initialize with empty directory structure")
+    bare: bool = Field(default=False, description="contentctl normally provides some some example content "
+                       "(macros, stories, data_sources, and/or analytic stories).  This option disables "
+                       "initialization with that additional contnet.  Note that even if --bare is used, it "
+                       "init will still create the directory structure of the app, "
+                       "include the app_template directory with default content, and content in "
+                       "the deployment/ directory (since it is not yet easily customizable).")
 
 
 # TODO (#266): disable the use_enum_values configuration