Old documentation update

.devcontainer/devcontainer.json

@@ -0,0 +1 @@
+{"image":"mcr.microsoft.com/devcontainers/universal:2"}

_documentation/cmfive-tests/enable-tests.md

@@ -15,13 +15,14 @@ Enabling the test framework is simple. Edit the file:
 cmfive-boilerplate/config.php
 ```
 Update the 'testrunner' setting to 'ENABLED'.
+
 ```php
 //========== TestRunner Configuration ==========================
 //========== must be "ENABLED" to run ==========================
 //========== "config" will pass through to CmfiveSite helper ===
 Config::append("tests", array(
-	"testrunner"  =>  "ENABLED" ,
-		'config' => [ ]
+    "testrunner"  =>  "ENABLED",
+    'config' => [ ]
 ));
 ```
 The Cmfive test libraries do not need any extra entries to be added in the TestRunner 'config' array setting.

_documentation/core-modules/insight/insight.md

@@ -13,9 +13,12 @@ The insight's class will be the sort of insight it is, followed by Insight (e.g.
 
 ```php
 class ExampleInsight extends InsightBaseClass
+{
+
+}
 ```
 
-Below this, give the variables for the insight's name and description. These will appear in the insight list, the first page seen in CMFive when you click on the insight module.
+In this class, add the variables below for the insight's name and description. These will appear in the insight list, the first page seen in CMFive when you click on the insight module.
 
 ```php
 public $name = "Example Insight";
@@ -26,72 +29,71 @@ These variables will indicate to users which insight is which.
 All insights will contain a getFilters function and a run function. The getFilters function will be called when a user clicks on the View button next to the insight. The run function is called when the user clicks Run from the view screen.
 
 getFilters will be an array, which sets up the parameters the user can choose. Before running an insight, the user may specify it to only show information from specific dates, for certain users, etc.<br>
-Add the below code underneath your name and description variables.
+Add the function below to your ExampleInsight class.
 
 ```php
 public function getFilters(Web $w, $parameters = []): array
 {
+
+}
 ```
 
 The filters you choose for the user to select from will depend on the insight you are creating.<br>
-The below code shows the code that goes in your getFilters function. This example has filters for choosing the date to and from that the insight shows.
-
+The code shown below goes in your getFilters function. It is what generates the filter options the user may choose from. This example has filters for choosing the date to and from that the insight shows.
 ```php
-    return [
-                "Options" => [
-                    [
-                        [
-                            "Date From", "date", "dt_from", array_key_exists('dt_from', $parameters) ? $parameters['dt_from'] : null
-                        ],
-                        [
-                            "Date To", "date", "dt_to", array_key_exists('dt_to', $parameters) ? $parameters['dt_to'] : null
-                        ],
-                    ]
-                ]
-            ];
-}
+return [
+    "Options" => [
+        [
+            [
+                "Date From", "date", "dt_from", array_key_exists('dt_from', $parameters) ? $parameters['dt_from'] : null
+            ],
+            [
+                "Date To", "date", "dt_to", array_key_exists('dt_to', $parameters) ? $parameters['dt_to'] : null
+            ],
+        ]
+    ]
+];
 ```
 
 You will notice that both filters contain an array_key_exists function. This is required on all filters in your insight. When you click the Change Insight Parameters button, the options you chose that session previously will be pre-filled for you.
 
 The run function will also be an array. It will find data based on the selected filters and then organise it into the appropriate columns for each table in the insight.<br>
-Place the below code under your getFilters function.
-
+Add the following function after your getFilters function.
 ```php
 public function run(Web $w, $parameters = []): array
 {
+
+}
 ```
-First, the insight finds the correct data based on the filters you have chosen. The data variable for our Example Insight will look like the code below.
 
+First, the insight finds the correct data based on the filters you have chosen. Add the following code to the run function to get the relevant data for our example insight.
 ```php
 $data = ExampleService::getInstance($w)->getExamples(($parameters['dt_from']), ($parameters['dt_to']));
 ```
 
 The getExamples function refers to a where array. In most cases you will not have to build one. Variables for all your data required for your insights tables can usually be created using existing service functions.
 
-After retrieving the data based on the selected filters, your run function must build its table(s). It will look something like this.
-
+After retrieving the data based on the selected filters, your run function must build its table(s). For our example, add the following code to the run function.
 ```php
 if (!$data) {
-             $results[] = new InsightReportInterface('Example Report', ['Results'], [['No data returned for selections']]);
-        } else {
-            // convert $data from list of objects to array of values
-            $convertedData = [];
+    $results[] = new InsightReportInterface('Example Report', ['Results'], [['No data returned for selections']]);
+} else {
+    // convert $data from list of objects to array of values
+    $convertedData = [];
 
-            foreach ($data as $datarow) {
-                $row = [];
-                $row['module'] = $datarow->module;
-                $row['url'] = $datarow->path;
-                $row['class'] = $datarow->db_class;
-                $row['action'] = $datarow->db_action;
-                $row['db_id'] = $datarow->db_id;
-                $convertedData[] = $row;
-            }
-             $results[] = new InsightReportInterface('Example Report', ['Module', 'URL', 'Class', 'Action', 'DB Id'], $convertedData);
-        }
-        return $results;
+    foreach ($data as $datarow) {
+        $row = [];
+        $row['module'] = $datarow->module;
+        $row['url'] = $datarow->path;
+        $row['class'] = $datarow->db_class;
+        $row['action'] = $datarow->db_action;
+        $row['db_id'] = $datarow->db_id;
+        $convertedData[] = $row;
     }
+    $results[] = new InsightReportInterface('Example Report', ['Module', 'URL', 'Class', 'Action', 'DB Id'], $convertedData);
 }
+
+return $results;
 ```
 
 The first few rows indicate what the insight will display if no data comes back.<br>

_documentation/core-modules/report/report.md

@@ -8,18 +8,20 @@ type: doc
 
 The report module allows users to write custom MYSQL reports that can be saved and run when needed.
 
+[comment]: # (The code snippet is indented so it can render the tabs correctly within the numbered list)
+
 ## Setup
 
 1. Before you learn how to use reports you'll need to make sure your config is setup correctly. Add the following entries into the <b>config.php</b> file in the root directory of your Cmfive project.
-```php
-Config::set("report.database", [
-    "hostname"  => "DB_HOSTNAME",
-    "username"  => "DB_USERNAME",
-    "password"  => "DB_PASSWORD",
-    "database"  => "DB_NAME",
-    "driver"    => "mysql"
-]);
-```
+    ```php
+    Config::set("report.database", [
+        "hostname"  => "DB_HOSTNAME",
+        "username"  => "DB_USERNAME",
+        "password"  => "DB_PASSWORD",
+        "database"  => "DB_NAME",
+        "driver"    => "mysql"
+    ]);
+    ```
 2. Replace <b>DB_HOSTNAME</b>, <b>DB_USERNAME</b>, <b>DB_PASSWORD</b> and <b>DB_NAME</b> with their respective values.
 3. To clear your config cache to apply your changes.
 

_tutorials/additional-configuration/emails.md

@@ -11,43 +11,52 @@ Cmfive supports two different types of email transports to best suit your needs.
 - The <b>AWS Transport</b> uses various AWS services to make sending email faster and more reliable. <b>Note</b>, to enable the AWS Transport uploads must also stored in S3. See the uploads <ins>[tutorial](/tutorials/additional-configuration/uploads)</ins> for setup.
 - The <b>SwiftMailer</b> transport uses the SwiftMailer library.
 
-## AWS Transport
+[comment]: # (The code snippets are indented so they work with the rendering of the numbered list of steps)
 
+## AWS Transport
 1. Add the following entries into the <b>config.php</b> file in the root directory of your Cmfive project.
-```php
-Config::append("email", [
-    "layer" => "aws",
-]);
-Config::set("admin.mail.aws", [
-   "queue_url" => "SQS_QUEUE_URL",
-   "region"    => "SQS_QUEUE_REGION",
-]);
-```
+    ```php
+    Config::append("email", [
+        "layer" => "aws",
+    ]);
+
+    Config::set("admin.mail.aws", [
+        "queue_url" => "SQS_QUEUE_URL",
+        "region"    => "SQS_QUEUE_REGION",
+    ]);
+    ```
+
 2. If you're developing on Cmfive locally, also add the following. <b>Note</b>, when system.environment is set to production <ins>[AWS IAM Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)</ins> must be used to authenticate with AWS as this is best practice for security.
-```php
-Config::set("admin.mail.aws.credentials", [
-    "key"    => "IAM_KEY",
-    "secret" => "IAM_SECRET",
-]);
-Config::set("system.environment", "development");
-```
+    ```php
+    Config::set("admin.mail.aws.credentials", [
+        "key"    => "IAM_KEY",
+        "secret" => "IAM_SECRET",
+    ]);
+
+    Config::set("system.environment", "development");
+    ```
+
 3. Replace <b>SQS_QUEUE_URL</b> and <b>SQS_QUEUE_REGION</b> with their respective values as well as <b>IAM_KEY</b> and <b>IAM_SECRET</b> if system.environment is set to development.
+
 4. Make sure to clear your config cache to apply your changes.
+
 5. Clone the Cmfive-Mail-Service-CDK <ins>[repository](https://github.com/2pisoftware/Cmfive-Mail-Service-CDK)</ins> and follow the steps outlined in the README.md file to deploy the CDK stack.
 
 ## SwiftMailer Transport
 
 1. Add the following entries into the <b>config.php</b> file in the root directory of your Cmfive project.
-```php
-Config::append("email", [
-    "layer"    => "smtp",
-    "command"  => "",
-    "host"     => "EMAIL_HOST",
-    "port"     => PORT_NUMBER,
-    "auth"     => true,
-    "username" => "EMAIL_USERNAME",
-    "password" => "EMAIL_PASSWORD",
-]);
-```
+    ```php
+    Config::append("email", [
+        "layer"    => "smtp",
+        "command"  => "",
+        "host"     => "EMAIL_HOST",
+        "port"     => PORT_NUMBER,
+        "auth"     => true,
+        "username" => "EMAIL_USERNAME",
+        "password" => "EMAIL_PASSWORD",
+    ]);
+    ```
+
 2. Replace <b>EMAIL_HOST</b>, <b>PORT_NUMBER</b>, <b>EMAIL_USERNAME</b> and <b>EMAIL_PASSWORD</b> with their respective values.
+
 3. Make sure to clear your config cache to apply your changes.

_tutorials/additional-configuration/logs.md

@@ -11,11 +11,13 @@ Cmfive supports two different types of log targets to best suit your needs.
 - The <b>AWS Target</b> provides a more reliable solution with the option to specify a retention period (in days).
 - The <b>File Target</b> is enabled by default and requires no further setup.
 
+[comment]: # (The code snippets are indented so they work with the rendering of the numbered list of steps)
+
 ## AWS Target
 
 1. Add the following entries into the <b>config.php</b> file in the root directory of your Cmfive project.
-```php
-Config::set("admin.logging", [
+    ```php
+    Config::set("admin.logging", [
         "target"           => "aws",
         "retention_period" => RETENTION_PERIOD,
         "cloudwatch"       => [
@@ -24,15 +26,19 @@ Config::set("admin.logging", [
             "region"          => "CLOUDWATCH_REGION",
             "version"         => "latest",
         ]
-]);
-```
+    ]);
+    ```
+
 2. If you're developing on Cmfive locally, also add the following. <b>Note</b>, when system.environment is set to production <ins>[AWS IAM Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)</ins> must be used to authenticate with AWS as this is best practice for security.
-```php
-Config::set("admin.logging.cloudwatch.credentials", [
-    "key"    => "IAM_KEY",
-    "secret" => "IAM_SECRET",
-]);
-Config::set("system.environment", "development");
-```
+    ```php
+    Config::set("admin.logging.cloudwatch.credentials", [
+        "key"    => "IAM_KEY",
+        "secret" => "IAM_SECRET",
+    ]);
+
+    Config::set("system.environment", "development");
+    ```
+
 3. Replace <b>RETENTION_PERIOD</b>, <b>GROUP_NAME</b>, <b>APP_NAME</b>, <b>CLOUDWATCH_REGION</b> with their respective values as well as <b>IAM_KEY</b> and <b>IAM_SECRET</b> if system.environment is set to development.
+
 4. Make sure to clear your config cache to apply your changes.

_tutorials/additional-configuration/uploads.md

@@ -11,35 +11,43 @@ Cmfive supports two different types of file adapters for uploads to best suit yo
 - The <b>Local Adapter</b> is enabled by default and requires no further setup.
 - The <b>S3 Adapter</b> provides a more available and reliable solution.
 
+[comment]: # (The code snippets are indented so they work with the rendering of the numbered list of steps)
+
 ## S3 Adapter
 
 1. Add the following entries into the <b>config.php</b> file in the root directory of your Cmfive project.
-```php
-Config::set("file.adapters.local.active", false);
-Config::set("file.adapters.s3", [
-   "active"      => true,
-   "region"      => "S3_BUCKET_REGION",
-   "version"     => "2006-03-01",
-   "credentials" => [
-       "key"    => "IAM_KEY",
-       "secret" => "IAM_SECRET",
-   ],
-   "bucket"      => "S3_BUCKET_NAME",
-   "options"     => [
-       "directory" => "uploads",
-       "create"    => true
-   ],
-]);
-```
+    ```php
+    Config::set("file.adapters.local.active", false);
+
+    Config::set("file.adapters.s3", [
+        "active"      => true,
+        "region"      => "S3_BUCKET_REGION",
+        "version"     => "2006-03-01",
+        "credentials" => [
+            "key"    => "IAM_KEY",
+            "secret" => "IAM_SECRET",
+        ],
+        "bucket"      => "S3_BUCKET_NAME",
+        "options"     => [
+            "directory" => "uploads",
+            "create"    => true
+        ],
+    ]);
+    ```
+
 2. If you're developing on Cmfive locally, also add the following. <b>Note</b>, when system.environment is set to production <ins>[AWS IAM Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)</ins> must be used to authenticate with AWS as this is best practice for security.
-```php
-Config::set("file.adapters.s3.credentials", [
-    "key"    => "IAM_KEY",
-    "secret" => "IAM_SECRET",
-]);
-Config::set("system.environment", "development");
-```
+    ```php
+    Config::set("file.adapters.s3.credentials", [
+        "key"    => "IAM_KEY",
+        "secret" => "IAM_SECRET",
+    ]);
+
+    Config::set("system.environment", "development");
+    ```
+
 3. Replace <b>S3_BUCKET_REGION</b>, <b>IAM_KEY</b>, <b>IAM_SECRET</b> and <b>S3_BUCKET_NAME</b> with their respective values as well as <b>IAM_KEY</b> and <b>IAM_SECRET</b> if system.environment is set to development.
+
 4. Make sure to clear your config cache to apply your changes.
+
 5. If you have any files stored locally from prior to using the S3 Adapter you can run <b>file transfer tool</b> in the admin module from within Cmfive to move them to S3.
 ![File Transfer Tool](/assets/images/file_transfer_tool.png)

_tutorials/installation/installation.md

@@ -25,8 +25,10 @@ Install the Docker extension by Microsoft (extension ID: ```ms-azuretools.vscode
 #### Step 3 - Building the containers
 Right-click on the ```docker-compose.yml``` file and select ```Compose Up``` (This will take a while)
 
+[comment]: # (Docker Tab image has an extra line of whitespace before it, otherwise it renders inline with the text)
 #### Step 4 - Verify
-When docker compose has finished, check that you have 3 containers ready by clicking on the Docker tab on the left
+When docker compose has finished, check that you have 3 containers ready by clicking on the Docker tab on the left.
+
 ![Docker Tab](/assets/images/docker.png)
 
 #### Step 5 - Connect to database container