Improved documentation (#20)

* Improve Auto Generated Doc Signed-off-by: Florian Wagner <[email protected]> * Add images Signed-off-by: Florian Wagner <[email protected]>
h2floh · Jan 3, 2020 · c24dfaf · c24dfaf
1 parent 0aa5ce4
commit c24dfaf
Show file tree

Hide file tree

Showing 42 changed files with 178 additions and 46 deletions.
diff --git a/Deploy/OneClickDeploy.ps1 b/Deploy/OneClickDeploy.ps1
@@ -30,7 +30,7 @@ After the script is successfully executed the bot should be in a usable state
 None. You cannot pipe objects.
 
 .OUTPUTS
-None
+System.Boolean. Returns $True if executed successfully
 
 #>
 param(
@@ -80,7 +80,7 @@ param(
 $success = $True
 # Import Helper functions
 . "$($MyInvocation.MyCommand.Path -replace($MyInvocation.MyCommand.Name))\HelperFunctions.ps1"
-# Tell who you are (See HelperFunction.ps1)
+# Tell who you are (See HelperFunctions.ps1)
 Write-WhoIAm
 
 # Validate Input parameter combination
@@ -128,4 +128,6 @@ if ($success -eq $False -or $validationresult -eq $False)
     Write-Host -ForegroundColor Red "`n`n# ERROR Occured while execution. Please check your output for errors and rerun the script or scriptlets.`n# Include the '-RERUN `$True' flag in case the execution of script 'DeployInfrastructure.ps1' was already successful."
 } else {
     Write-ExecutionStatus -success $success
-}
+}
+
+exit $success
diff --git a/Doc/CreateMarkdown-FromPS1.ps1 b/Doc/CreateMarkdown-FromPS1.ps1
@@ -40,7 +40,7 @@ function Get-ParameterMarkdownTable {
         [object] $help
     )
 
-    $result = "| Name | Type | Required | Default | Description |`n| - | - | - | - | - |"
+    $result = "`n`n## Parameters`n`n| Name | Type | Required | Default | Description |`n| - | - | - | - | - |"
 
     #Write-Host $help
 
@@ -62,7 +62,13 @@ function Get-ParameterMarkdownTable {
         $result += "`n| $($_.name) | $($_.type.name) | $($_.required) | $($default) | $($description) |"
     })
 
-    return $result
+    if ($help.parameters -ne "")
+    {
+        return $result
+    } else {
+        return ""
+    }
+
 }
 
 function Get-Examples {
@@ -93,6 +99,8 @@ function Get-FlowChart {
     $flowchartfile = "flowchart/$($fileparts[0]).flowchart"
     if (Test-Path -Path $flowchartfile)
     {
+        # Force LF style
+        (Get-Content $flowchartfile -Raw).Replace("`r`n","`n") | Set-Content $flowchartfile -Force
         # render flowchart
         diagrams flowchart $flowchartfile > $null 
 
@@ -101,7 +109,38 @@ function Get-FlowChart {
     } else {
         return ""
     }
+}
+
+function Get-RelatedScripts {
+    param (
+        # PS1 file
+        [Parameter(Mandatory=$True,HelpMessage="PS1 file")]
+        [object] $file
+    )
+
+    $script = Get-Content -Path $file.FullName
+
+    $results = $script | Select-String "([\w]+)\.ps1" -AllMatches
 
+    # Display only Unique values
+    $matches = $results.Matches.Value | Select-Object -uniq
+    # Remove self references
+    $matches = $matches -ne $file.name 
+    # Remove Helper Function references
+    $matches = $matches -ne "HelperFunctions.ps1"
+    $matches = $matches -ne "HelperFunction.ps1"
+    $matches.foreach({
+        $fileparts = $_.Split('.')
+        $related += "`n- [$_]($($fileparts[0]).md)`n"
+    })    
+
+    #Write-Host $results.Matches
+
+    if ($null -ne $related) {
+        return "`n`n## Related Scripts$related"
+    } else {
+        return ""
+    }
 }
 
 function ConvertHelpToMarkdown {
@@ -129,13 +168,15 @@ function ConvertHelpToMarkdown {
         $markdown += "`n`n## Description`n`n$($help.description.text)"
 
         # Parameters
-        $parameters = Get-ParameterMarkdownTable -help $help
-        $markdown += "`n`n## Parameters`n`n$($parameters)"
+        $markdown += Get-ParameterMarkdownTable -help $help
 
         # Examples
         $examples = Get-Examples -help $help
         $markdown += "`n`n## Examples`n`n$($examples)"
 
+        # Get Related Script
+        $markdown += Get-RelatedScripts -file $file
+
         # flowchart
         $markdown += Get-FlowChart -file $file.name
 

diff --git a/Doc/Deploy/CreateOrImportSSL.md b/Doc/Deploy/CreateOrImportSSL.md
@@ -47,6 +47,22 @@ After the script is successfully executed the Bot should be in a usable from wit
 ```
 
 
+## Related Scripts
+- [OneClickDeploy.ps1](OneClickDeploy.md)
+
+- [ValidateParameter.ps1](ValidateParameter.md)
+
+- [CheckExistingSSL.ps1](CheckExistingSSL.md)
+
+- [DeactivateSSL.ps1](DeactivateSSL.md)
+
+- [ImportSSL.ps1](ImportSSL.md)
+
+- [CreateSSL.ps1](CreateSSL.md)
+
+- [ActivateSSL.ps1](ActivateSSL.md)
+
+
 ## Flowchart
 
 <div align='center'>

diff --git a/Doc/Deploy/CreateSSL.md b/Doc/Deploy/CreateSSL.md
@@ -35,6 +35,10 @@ After the script is successfully executed the certificate should be stored in Ke
 ```
 
 
+## Related Scripts
+- [ActivateSSL.ps1](ActivateSSL.md)
+
+
 ## Flowchart
 
 <div align='center'>

diff --git a/Doc/Deploy/DeactivateSSL.md b/Doc/Deploy/DeactivateSSL.md
@@ -11,11 +11,6 @@ This script will do following steps:
 1. Read relevant data of TrafficManager from Terraform Infrastructure execution
 2. Delete all TrafficManager endpoints, this will also remove the custom domain name entry from WebApps automatically
 
-## Parameters
-
-| Name | Type | Required | Default | Description |
-| - | - | - | - | - |
-
 ## Examples
 
 ```powershell

diff --git a/Doc/Deploy/OneClickDeploy.md b/Doc/Deploy/OneClickDeploy.md
@@ -44,6 +44,20 @@ After the script is successfully executed the bot should be in a usable state
 ```
 
 
+## Related Scripts
+- [ValidateParameter.ps1](ValidateParameter.md)
+
+- [DeployInfrastructure.ps1](DeployInfrastructure.md)
+
+- [DeployLUIS.ps1](DeployLUIS.md)
+
+- [DeployBot.ps1](DeployBot.md)
+
+- [CreateOrImportSSL.ps1](CreateOrImportSSL.md)
+
+- [RetrieveWebChatLink.ps1](RetrieveWebChatLink.md)
+
+
 ## Flowchart
 
 <div align='center'>

diff --git a/Doc/Deploy/OneClickDestroy.md b/Doc/Deploy/OneClickDestroy.md
@@ -34,6 +34,10 @@ After the script is successfully executed there should be nothing left
 ```
 
 
+## Related Scripts
+- [ExportSSL.ps1](ExportSSL.md)
+
+
 ## Flowchart
 
 <div align='center'>

diff --git a/Doc/Deploy/RetrieveWebChatLink.md b/Doc/Deploy/RetrieveWebChatLink.md
@@ -13,11 +13,6 @@ This script will do following steps:
 
 After the script is successfully executed you should have a link to check you bot
 
-## Parameters
-
-| Name | Type | Required | Default | Description |
-| - | - | - | - | - |
-
 ## Examples
 
 ```powershell

diff --git a/Doc/Deploy/ValidateParameter.md b/Doc/Deploy/ValidateParameter.md
@@ -42,6 +42,10 @@ After the script is successfully executed it should be ensured that the deployme
 ```
 
 
+## Related Scripts
+- [OneClickDeploy.ps1](OneClickDeploy.md)
+
+
 ## Flowchart
 
 <div align='center'>

diff --git a/Doc/flowchart/CreateOrImportSSL.flowchart.svg b/Doc/flowchart/CreateOrImportSSL.flowchart.svg
diff --git a/Doc/flowchart/OneClickDeploy.flowchart.svg b/Doc/flowchart/OneClickDeploy.flowchart.svg
diff --git a/Doc/flowchart/OneClickDestroy.flowchart.svg b/Doc/flowchart/OneClickDestroy.flowchart.svg
diff --git a/Doc/flowchart/activatessl.flowchart b/Doc/flowchart/activatessl.flowchart
@@ -4,4 +4,6 @@ t1=>operation: Read IaC Terraform execution output
 t2=>operation: Apply SSLActivation Terraform
 b=>operation: Update Bot Registration Endpoint
 
-st->t1->t2->b->e
+st->t1->t2->b->e
+
+
diff --git a/Doc/flowchart/checkexistingssl.flowchart b/Doc/flowchart/checkexistingssl.flowchart
@@ -3,4 +3,6 @@ e=>end: End
 t1=>operation: Read IaC Terraform execution output
 t2=>operation: Check if SSL certificate exists in KeyVault
 
-st->t1->t2->e
+st->t1->t2->e
+
+
diff --git a/Doc/flowchart/createorimportssl.flowchart b/Doc/flowchart/createorimportssl.flowchart
@@ -1,11 +1,11 @@
 st=>start: Start
 e=>end: End
-val=>operation: Validation:>ValidateParameter.md
-check=>operation: CheckExistingSSL:>CheckExistingSSL.md
-deactivate=>operation: DeactivateSSL:>DeactivateSSL.md
-import=>operation: ImportSSL:>ImportSSL.md
-create=>operation: CreateSSL:>CreateSSL.md
-activate=>operation: ActivateSSL:>ActivateSSL.md
+val=>operation: ValidateParameter.ps1:>ValidateParameter.md
+check=>operation: CheckExistingSSL.ps1:>CheckExistingSSL.md
+deactivate=>operation: DeactivateSSL.ps1:>DeactivateSSL.md
+import=>operation: ImportSSL.ps1:>ImportSSL.md
+create=>operation: CreateSSL.ps1:>CreateSSL.md
+activate=>operation: ActivateSSL.ps1:>ActivateSSL.md
 
 succ=>condition: Success?
 exists=>condition: SSL Exists?
@@ -25,3 +25,6 @@ pfx(no)->create
 import->activate
 create->activate
 activate->e
+
+
+
diff --git a/Doc/flowchart/createssl.flowchart b/Doc/flowchart/createssl.flowchart
@@ -13,4 +13,6 @@ st->t1->cust
 cust(yes)->cname
 cust(no)->t2
 cname->t2
-t2->kvcheck->t3->e
+t2->kvcheck->t3->e
+
+
diff --git a/Doc/flowchart/deactivatessl.flowchart b/Doc/flowchart/deactivatessl.flowchart
@@ -3,4 +3,6 @@ e=>end: End
 t1=>operation: Read IaC Terraform execution output
 t2=>operation: Delete all TrafficManager endpoints
 
-st->t1->t2->e
+st->t1->t2->e
+
+
diff --git a/Doc/flowchart/deploybot.flowchart b/Doc/flowchart/deploybot.flowchart
@@ -6,4 +6,6 @@ d3=>operation: ZIP resources
 d4=>operation: Load WebApps data from IaC Terraform output
 d5=>operation: ZIP Deploy to each WebApp
 
-st->d1->d2->d3->d4->d5->e
+st->d1->d2->d3->d4->d5->e
+
+
diff --git a/Doc/flowchart/deployinfrastructure.flowchart b/Doc/flowchart/deployinfrastructure.flowchart
@@ -2,4 +2,6 @@ st=>start: Start
 e=>end: End
 t1=>operation: Apply IaC Terraform script
 
-st->t1->e
+st->t1->e
+
+
diff --git a/Doc/flowchart/deployluis.flowchart b/Doc/flowchart/deployluis.flowchart
@@ -15,4 +15,6 @@ app=>condition: Does LUIS App already exists?
 st->l1->l2->app
 app(yes)->u->l3
 app(no)->i->l3
-l3->l4->l5->l6->l7->e
+l3->l4->l5->l6->l7->e
+
+
diff --git a/Doc/flowchart/exportssl.flowchart b/Doc/flowchart/exportssl.flowchart
@@ -13,4 +13,6 @@ os=>condition: Script runs on Windows?
 st->l1->l2->os
 os(yes)->winp->l3
 os(no)->unixp->l3
-l3->e
+l3->e
+
+
diff --git a/Doc/flowchart/importssl.flowchart b/Doc/flowchart/importssl.flowchart
@@ -3,4 +3,6 @@ e=>end: End
 l1=>operation: Load KeyVault data from IaC Terraform output
 l2=>operation: Import given PFX file to KeyVault
 
-st->l1->l2->e
+st->l1->l2->e
+
+
diff --git a/Doc/flowchart/oneclickdeploy.flowchart b/Doc/flowchart/oneclickdeploy.flowchart
@@ -1,11 +1,11 @@
 st=>start: Start
 e=>end: End
-val=>operation: Validation:>ValidateParameter.md
-di=>operation: DeployInfrastructure:>DeployInfrastructure.md
-dl=>operation: DeployLUIS:>DeployLUIS.md
-db=>operation: DeployBot:>DeployBot.md
-cis=>operation: CreateOrImportSSL:>CreateOrImportSSL.md
-re=>operation: RetrieveWebChatLink:>RetrieveWebChatLink.md
+val=>operation: ValidateParameter.ps1:>ValidateParameter.md
+di=>operation: DeployInfrastructure.ps1:>DeployInfrastructure.md
+dl=>operation: DeployLUIS.ps1:>DeployLUIS.md
+db=>operation: DeployBot.ps1:>DeployBot.md
+cis=>operation: CreateOrImportSSL.ps1:>CreateOrImportSSL.md
+re=>operation: RetrieveWebChatLink.ps1:>RetrieveWebChatLink.md
 succ1=>condition: Success?
 succ2=>condition: Success?
 succ3=>condition: Success?
@@ -27,4 +27,21 @@ succ4(no)->e
 cis->succ5
 succ5(yes)->re
 succ5(no)->e
-re->e
+re->e
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/Doc/flowchart/oneclickdestroy.flowchart b/Doc/flowchart/oneclickdestroy.flowchart
@@ -1,10 +1,12 @@
 st=>start: Start
 e=>end: End
-ex=>operation: Export SSL:>ExportSSL.md
+ex=>operation: ExportSSL.ps1:>ExportSSL.md
 de=>operation: Execute Terraform destroy on IaC folder
 a=>condition: AUTOAPPROVE = True ?
 st->a
 a(yes)->de
 a(no)->ex
 ex->de
-de->e
+de->e
+
+