Fix docs sidebar + tests (#2)

1. Switch from autogen sidebar to manual. This allows for better
control.
2. Add Pester tests to confirm that all markdown files are in the
sidebar.ts

.vscode/settings.json

@@ -1,3 +1,8 @@
 {
   "frontMatter.dashboard.openOnStart": true,
+  "files.trimTrailingWhitespace": true,
+  "files.insertFinalNewline": true,
+  "editor.insertSpaces": true,
+  "editor.tabSize": 2,
+  "powershell.codeFormatting.preset": "OTBS"
 }

.vscode/tasks.json

@@ -45,5 +45,14 @@
         "isDefault": true
       }
     },
+    {
+      "label": "Test",
+      "type": "shell",
+      "command": "${cwd}/build.ps1 -Task Test -Verbose",
+      "group": {
+        "kind": "test",
+        "isDefault": true
+      }
+    },
   ]
-}
+}

docs/tutorial-basics/property-overrides.md → docs/tutorial-basics/parameters-properties.md

@@ -1,49 +1,79 @@
----
-description: "How to override a property in your build script."
-sidebar_position: 11
----
-
-# Properties
-
-You can override a property in your build script using the `properties`
-parameter of the Invoke-psake function. The following is an example:
-
-```powershell
-Invoke-psake .\properties.ps1 -properties @{"x"="1";"y"="2"}
-```
-
-The example above runs the build script called "properties.ps1" and passes in
-parameters 'x' and 'y' with values '1' and '2'. The parameter value for the
-"properties" parameter is a PowerShell hashtable where the name and value of
-each property is specified. Note: You don't need to use the "$" character when
-specifying the property names in the hashtable.
-
-The "properties.ps1" build script looks like this:
-
-```powershell
-properties {
- $x = $null
- $y = $null
- $z = $null
-}
-
-task default -depends TestProperties
-
-task TestProperties {
-  Assert ($x -ne $null) "x should not be null"
-  Assert ($y -ne $null) "y should not be null"
-  Assert ($z -eq $null) "z should be null"
-}
-```
-
-The value of $x should be 1 and $y should be 2 by the time the "TestProperties"
-task is executed. The value of $z was not over-ridden so it should still be
-$null.
-
-To summarize the differences between passing parameters and properties to the
-Invoke-psake function:
-
-* Parameters and "properties" can both be passed to the Invoke-psake function
-  simultaneously
-* Parameters are set before any "properties" blocks are run
-* Properties are set after all "properties" blocks have run
+---
+description: "How to use parameters and properties in your build script."
+sidebar_position: 11
+---
+
+# Parameters & Properties
+
+To summarize the differences between passing parameters and properties to the
+`Invoke-psake` function:
+
+* Parameters and "properties" can both be passed to the Invoke-psake function
+  simultaneously
+* Parameters are set before any "properties" blocks are run
+* Properties are set after all "properties" blocks have run
+
+## Parameters
+
+You can pass parameters to your build script using the "parameters" parameter of
+the Invoke-psake function. The following is an example:
+
+```powershell
+Invoke-psake .\parameters.ps1 -parameters @{"p1"="v1";"p2"="v2"}
+```
+
+The example above runs the build script called "parameters.ps1" and passes in
+parameters 'p1' and 'p2' with values 'v1' and 'v2'. The parameter value for the
+"parameters" parameter (say that 10 times really fast!) is a PowerShell
+hashtable where the name and value of each parameter is specified. Note: You
+don't need to use the "$" character when specifying the parameter names in the
+hashtable.
+
+```powershell title="parameters.ps1"
+properties {
+  $my_property = $p1 + $p2
+}
+
+task default -depends TestParams
+
+task TestParams {
+  Assert ($my_property -ne $null) '$my_property should not be null'
+}
+```
+
+## Properties
+
+You can override a property in your build script using the `properties`
+parameter of the Invoke-psake function. The following is an example:
+
+```powershell
+Invoke-psake .\properties.ps1 -properties @{"x"="1";"y"="2"}
+```
+
+The example above runs the build script called "properties.ps1" and passes in
+parameters 'x' and 'y' with values '1' and '2'. The parameter value for the
+"properties" parameter is a PowerShell hashtable where the name and value of
+each property is specified. Note: You don't need to use the "$" character when
+specifying the property names in the hashtable.
+
+The "properties.ps1" build script looks like this:
+
+```powershell
+properties {
+ $x = $null
+ $y = $null
+ $z = $null
+}
+
+task default -depends TestProperties
+
+task TestProperties {
+  Assert ($x -ne $null) "x should not be null"
+  Assert ($y -ne $null) "y should not be null"
+  Assert ($z -eq $null) "z should be null"
+}
+```
+
+The value of $x should be 1 and $y should be 2 by the time the "TestProperties"
+task is executed. The value of $z was not over-ridden so it should still be
+$null.

docs/tutorial-basics/pass-parameters.md → docs/tutorial-basics/parameters.md

@@ -1,30 +1,30 @@
----
-sidebar_position: 6
----
-# Parameters
-
-You can pass parameters to your build script using the "parameters" parameter of
-the Invoke-psake function. The following is an example:
-
-```powershell
-Invoke-psake .\parameters.ps1 -parameters @{"p1"="v1";"p2"="v2"}
-```
-
-The example above runs the build script called "parameters.ps1" and passes in
-parameters 'p1' and 'p2' with values 'v1' and 'v2'. The parameter value for the
-"parameters" parameter (say that 10 times really fast!) is a PowerShell
-hashtable where the name and value of each parameter is specified. Note: You
-don't need to use the "$" character when specifying the parameter names in the
-hashtable.
-
-```powershell title="parameters.ps1"
-properties {
-  $my_property = $p1 + $p2
-}
-
-task default -depends TestParams
-
-task TestParams { 
-  Assert ($my_property -ne $null) '$my_property should not be null'  
-}
-```
+---
+sidebar_position: 6
+---
+# Parameters
+
+You can pass parameters to your build script using the "parameters" parameter of
+the Invoke-psake function. The following is an example:
+
+```powershell
+Invoke-psake .\parameters.ps1 -parameters @{"p1"="v1";"p2"="v2"}
+```
+
+The example above runs the build script called "parameters.ps1" and passes in
+parameters 'p1' and 'p2' with values 'v1' and 'v2'. The parameter value for the
+"parameters" parameter (say that 10 times really fast!) is a PowerShell
+hashtable where the name and value of each parameter is specified. Note: You
+don't need to use the "$" character when specifying the parameter names in the
+hashtable.
+
+```powershell title="parameters.ps1"
+properties {
+  $my_property = $p1 + $p2
+}
+
+task default -depends TestParams
+
+task TestParams { 
+  Assert ($my_property -ne $null) '$my_property should not be null'  
+}
+```

docs/tutorial-basics/conditional-task.md → docs/tutorial-basics/tasks.md

@@ -1,51 +1,91 @@
----
-sidebar_position: 4
----
-# Conditional Tasks
-
-You can conditionally run a task by using the "precondition" parameter of the
-"task" function. The "precondition" parameter expects a scriptblock as its value
-and that scriptblock should return a $true or $false.
-
-The following is an example build script that uses the "precondition" parameter
-of the task function:
-
-```powershell
-task default -depends A,B,C
-
-task A {
-  "TaskA"
-}
-
-task B -precondition { return $false } {
-  "TaskB"
-}
-
-task C -precondition { return $true } {
-  "TaskC"
-}
-```
-
-The output from running the above build script looks like the following:
-
-```powershell
-Executing task: A
-TaskA
-Precondition was false not executing B
-Executing task: C
-TaskC
-
-Build Succeeded!
-
-----------------------------------------------------------------------
-Build Time Report
-----------------------------------------------------------------------
-Name   Duration
-----   --------
-A      00:00:00.0231283
-B      0
-C      00:00:00.0043444
-Total: 00:00:00.1405840
-```
-
-Notice how task "B" was not executed and its run-time duration was 0 secs.
+---
+sidebar_position: 4
+---
+# Tasks
+
+At the core of psake is the task. In it's simplest form you have a task with a
+name and an action.
+
+```powershell
+task Hello {
+  "Hello world"
+}
+```
+
+This is the equivalent:
+
+```powershell
+Task -Name "Hello" -Action {
+  "Hello world"
+}
+```
+
+## Dependencies
+
+The power of psake is in it's ability to support dependencies. You can add
+`-Depends` to your task and give it a list of other tasks that need to run
+before it does.
+
+```powershell
+Task PBJ -Depends Toast, PB, Jelly {
+  "Enjoy sandwich!"
+}
+Task Toast {
+  "Toast 2 pieces of bread"
+}
+Task PB {
+  "Spread some peanut butter"
+}
+Task Jelly {
+  "Spread some jelly"
+}
+```
+
+## Conditional Tasks
+
+You can conditionally run a task by using the "precondition" parameter of the
+"task" function. The "precondition" parameter expects a scriptblock as its value
+and that scriptblock should return a $true or $false.
+
+The following is an example build script that uses the "precondition" parameter
+of the task function:
+
+```powershell
+task default -depends A,B,C
+
+task A {
+  "TaskA"
+}
+
+task B -precondition { return $false } {
+  "TaskB"
+}
+
+task C -precondition { return $true } {
+  "TaskC"
+}
+```
+
+The output from running the above build script looks like the following:
+
+```powershell
+Executing task: A
+TaskA
+Precondition was false not executing B
+Executing task: C
+TaskC
+
+Build Succeeded!
+
+----------------------------------------------------------------------
+Build Time Report
+----------------------------------------------------------------------
+Name   Duration
+----   --------
+A      00:00:00.0231283
+B      0
+C      00:00:00.0043444
+Total: 00:00:00.1405840
+```
+
+Notice how task "B" was not executed and its run-time duration was 0 secs.

docusaurus.config.ts

@@ -1,3 +1,4 @@
+// cSpell:ignore Untruncated
 import { themes as prismThemes } from 'prism-react-renderer';
 import type { Config } from '@docusaurus/types';
 import type * as Preset from '@docusaurus/preset-classic';