Release merge for v0.3.0 (#6)

* Added vscode task for code coverage reporting

* Updated CI metadata

* Added vscode settings to exclude paths

* Documentation updates

* Updated Yaml processing to keep header order and allow header merging

* Quality updates for unit testing

* Added message strings

* Fix to prevent Yaml block from being processed when not explictly used

* Updated Title keyword processing to handle multiple definitions

* Added SharePoint documentation example

* Documentation updates

* Minor documentation updates

* Updated tasks.json to use new schema

* Moved cmdlet help docs

* Reorgansed docs for scaffolding with platyPS

* Added documentation updates

* Fix documentation links on readme

* Minor update to error handling in BuildDocumentation

* Dependency and version update preparing for next release

* Update documentation build tasks

* Update tests and error handling

* Documentation updates

* Correction to change log grammer

* Updates to link external help

* Added launch file for debugging

* Further documentation updates

* Updated change log and readme

* Updates to help and remove -Path parameter which is for a future use case

* Updates for cmdlet help

* Improved code block handling

* Updated documentation links

* Updates to include about topics in document build process

* Updated script to clean up old docs

* Added cleanup of docs build path

* Added common parameters

* Added keyword about help

* Merged into keywords document

* Removed configuration data parameter for Invoke-PSDocument

* Fix up build task to prevent matcher prompt

* Updated documentation

* Automatically create OutputPath if it doesn't exist

* Added PSDocs.Dsc to build task

* Preparing for v0.3.0

.codecov.yml

@@ -2,7 +2,7 @@ codecov:
   notify:
     require_ci_to_pass: no
   # dev should be the baseline for reporting
-  branch: dev
+  branch: master
 
 comment:
   layout: "reach, diff"

.gitignore

@@ -6,4 +6,5 @@
 /build/
 /reports/
 /**/*.user
-/.vscode/settings.json
+/src/**/*-help.xml
+/src/**/*.help.txt

.vscode/launch.json

@@ -0,0 +1,45 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "type": "PowerShell",
+            "request": "launch",
+            "name": "PowerShell Launch Current File",
+            "script": "${file}",
+            "args": [],
+            "cwd": "${file}"
+        },
+        {
+            "type": "PowerShell",
+            "request": "launch",
+            "name": "PowerShell Launch Current File in Temporary Console",
+            "script": "${file}",
+            "args": [],
+            "cwd": "${file}",
+            "createTemporaryIntegratedConsole": true
+        },
+        {
+            "type": "PowerShell",
+            "request": "launch",
+            "name": "PowerShell Launch Current File w/Args Prompt",
+            "script": "${file}",
+            "args": [
+                "${command:SpecifyScriptArgs}"
+            ],
+            "cwd": "${file}"
+        },
+        {
+            "type": "PowerShell",
+            "request": "attach",
+            "name": "PowerShell Attach to Host Process",
+            "processId": "${command:PickPSHostProcess}",
+            "runspaceId": 1
+        },
+        {
+            "type": "PowerShell",
+            "request": "launch",
+            "name": "PowerShell Interactive Session",
+            "cwd": "${workspaceRoot}"
+        }
+    ]
+}

.vscode/settings.json

@@ -0,0 +1,10 @@
+{
+    "files.exclude": {
+        ".vs": true,
+        "artifacts": true,
+        "reports": true
+    },
+    "search.exclude": {
+        "build": true
+    }
+}

.vscode/tasks.json

@@ -4,7 +4,7 @@
     "version": "2.0.0",
     "tasks": [
         {
-            "taskName": "test",
+            "label": "test",
             "type": "shell",
             "command": ".\\scripts\\test.ps1",
             "group": {
@@ -14,13 +14,38 @@
             "problemMatcher": [ "$pester" ]
         },
         {
-            "taskName": "build",
+            "label": "coverage",
             "type": "shell",
-            "command": ".\\scripts\\build.ps1 -Clean -Module PSDocs",
+            "command": ".\\scripts\\test.ps1 -Clean -CodeCoverage",
+            "problemMatcher": [ "$pester" ]
+        },
+        {
+            "label": "build",
+            "type": "shell",
+            "command": ".\\scripts\\build.ps1 -Clean -Module PSDocs,PSDocs.Dsc",
             "group": {
                 "kind": "build",
                 "isDefault": true
-            }
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "build-docs",
+            "type": "shell",
+            "command": ".\\scripts\\build-docs.ps1",
+            "problemMatcher": []
+        },
+        {
+            "label": "scaffold-docs",
+            "type": "shell",
+            "command": ".\\scripts\\build-docs.ps1 -Scaffold",
+            "problemMatcher": []
+        },
+        {
+            "label": "clean",
+            "type": "shell",
+            "command": "Remove-Item -Path .\\build -Recurse -Force",
+            "problemMatcher": []
         }
     ]
 }

CHANGELOG.md

@@ -0,0 +1,26 @@
+
+## Unreleased
+
+## v0.3.0
+
+- Improved `Yaml` block handling to allow yaml header to be defined throughout the document and merged when multiple blocks are defined
+- Improved cmdlet help
+- Output path is automatically created by `Invoke-PSDocument` if it doesn't exist
+- Fix to improve handling when `Title` block is used multiple times
+- Fix to prevent yaml header being created when `Yaml` block is not used
+- Code blocks now generate fenced sections instead of indented sections
+- [Breaking change] The body of Code blocks are now no longer evaluated as an expression
+  - This change improves editing of document templates, allowing editors to complete valid PowerShell syntax
+  - Define an expression and the pipe the results to the Code keyword to dynamically generate the contents of a code block
+- [Breaking change] `-ConfigurationData` parameter of `Invoke-PSDocument` has been removed while purpose and future use of the parameter is reconsidered
+
+## v0.2.0
+
+- Added Desired State Configuration (DSC) extension module PSDocs.Dsc to generate markdown from DSC .mof files
+- Moved markdown processor to a seperate module
+- Fix handling of multi-line notes and warnings
+- Added support to include documentation from external script file
+
+## v0.1.0
+
+- Initial release

README.md

@@ -1,39 +1,42 @@
 # PSDocs
+
 A PowerShell module with commands to generate markdown from objects using PowerShell syntax.
 
 | AppVeyor (Windows) | Codecov (Windows) |
 | --- | --- |
 | [![av-image][]][av-site] | [![cc-image][]][cc-site] |
 
 [av-image]: https://ci.appveyor.com/api/projects/status/pl7tu7ktue388n7s
-[av-site]: https://ci.appveyor.com/project/BernieWhite/psdocs
+[av-site]: https://ci.appveyor.com/project/BernieWhite/PSDocs
 [cc-image]: https://codecov.io/gh/BernieWhite/PSDocs/branch/master/graph/badge.svg
 [cc-site]: https://codecov.io/gh/BernieWhite/PSDocs
 
 ## Disclaimer
+
 This project is to be considered a **proof-of-concept** and **not a supported Microsoft product**.
 
 ## Modules
+
 The following modules are included in this repository.
 
 | Module     | Description | Latest version |
 | ------     | ----------- | -------------- |
-| PSDocs     | Generate markdown from PowerShell | [v0.2.0][psg-psdocs] |
-| PSDocs.Dsc | Extension for PSDocs to generate markdown from Desired State Configuration | [v0.2.0][psg-psdocsdsc] |
+| PSDocs     | Generate markdown from PowerShell | [v0.3.0][psg-psdocs] |
+| PSDocs.Dsc | Extension for PSDocs to generate markdown from Desired State Configuration | [v0.3.0][psg-psdocsdsc] |
 
 [psg-psdocs]: https://www.powershellgallery.com/packages/PSDocs
 [psg-psdocsdsc]: https://www.powershellgallery.com/packages/PSDocs.Dsc
 
 ## Getting started
 
-### 1. Prerequsits
+### Prerequsits
 
 - Windows Management Framework (WMF) 5.0 or greater
 - .NET Framework 4.6 or greater
 
-### 2. Get PSDocs
+### Getting the modules
 
-- Install from PowerShellGallery.com
+- Install from [PowerShell Gallery][psg-psdocs]
 
 ```powershell
 # Install base PSDocs module
@@ -45,15 +48,26 @@ Install-Module -Name 'PSDocs';
 Install-Module -Name 'PSDocs.Dsc';
 ```
 
-### 3. Usage
+- Save for offline use from PowerShell Gallery
+
+```powershell
+# Save PSDocs module, in the .\modules directory
+Save-Module -Name 'PSDocs' -Path '.\modules';
+
+# Save PSDocs.Dsc module, in the .\modules directory
+Save-Module -Name 'PSDocs.Dsc' -Path '.\modules';
+```
+
+### Generate a document from a directory listing
 
 ```powershell
 # Import PSDocs module
 Import-Module -Name PSDocs;
 
-# Define a sample document
-document Sample {
+# Define a document called Sample
+Document Sample {
 
+    # Add an introduction section
     Section Introduction {
         # Add a comment
         "This is a sample file list from $InputObject"
@@ -63,33 +77,75 @@ document Sample {
     }
 }
 
-# Call the sample document and generate markdown
-Invoke-PSDocument -Name Sample -InputObject 'C:\';
+# Call the document definition and generate markdown from an object
+Invoke-PSDocument -Name 'Sample' -InputObject 'C:\';
 ```
 
-For an example of the output generated see [Get-ChildItemExample](/docs/examples/Get-child-item-output.md)
+An example of the output generated is available [here](/docs/examples/Get-child-item-output.md).
+
+### Generate documentation from Desired State Configuration
+
+```powershell
+# Import PSDocs.Dsc module
+Import-Module -Name PSDocs.Dsc;
+
+# Define a document called Sample
+Document 'Sample' {
+
+    # Add an 'Installed features' section in the document
+    Section 'Installed features' {
+        # Add a comment
+        'The following Windows features have been installed.'
+
+        # Generate a table of Windows Features
+        $InputObject.ResourceType.WindowsFeature | Table -Property Name,Ensure
+    }
+}
+
+# Call the document definition and generate markdown for each .mof file in the .\nodes directory
+Invoke-DscNodeDocument -DocumentName 'Sample' -Path '.\nodes' -OutputPath '.\docs';
+```
 
 ## Language reference
 
+PSDocs extends PowerShell with domain specific lanagage (DSL) keywords and cmdlets.
+
 ### Keywords
 
-- [Document](/docs/keywords/Document.md)
-- [Section](/docs/keywords/Section.md)
-- [Code](/docs/keywords/Code.md)
-- [Note](/docs/keywords/Note.md)
-- [Warning](/docs/keywords/Warning.md)
-- [Yaml](/docs/keywords/Yaml.md)
-- [Table](/docs/keywords/Table.md)
+The following language keywords are used by the `PSDocs` module:
+
+- [Document](/docs/keywords/PSDocs/en-US/Document.md) - Defines a named documentation block
+- [Section](/docs/keywords/PSDocs/en-US/Section.md) - Creates a named section
+- [Title](/docs/keywords/PSDocs/en-US/Title.md) - Sets the document title
+- [Code](/docs/keywords/PSDocs/en-US/Code.md) - Inserts a block of code
+- [Note](/docs/keywords/PSDocs/en-US/Note.md) - Inserts a note using DocFx formatted markdown (DFM)
+- [Warning](/docs/keywords/PSDocs/en-US/Warning.md) - Inserts a warnding usinf DocFx formatted markdown (DFM)
+- [Yaml](/docs/keywords/PSDocs/en-US/Yaml.md) - Inserts a YAML header
+- [Table](/docs/keywords/PSDocs/en-US/Table.md) - Inserts a table from pipeline objects
 
 ### Commands
 
-- [Invoke-PSDocument](/docs/commands/Invoke-PSDocument.md)
-- [Invoke-DscNodeDocument](/docs/commands/Invoke-DscNodeDocument.md)
+The following commands exist in the `PSDocs` module:
+
+- [Invoke-PSDocument](/docs/commands/PSDocs/en-US/Invoke-PSDocument.md)
+- [Get-PSDocumentHeader](/docs/commands/PSDocs/en-US/Get-PSDocumentHeader.md)
+- [Import-PSDocumentTemplate](/docs/commands/PSDocs/en-US/Import-PSDocumentTemplate.md)
+
+The following commands exist in the `PSDocs.Dsc` module:
+
+- [Get-DscMofDocument](/docs/commands/PSDocs.Dsc/en-US/Get-DscMofDocument.md)
+- [Invoke-DscNodeDocument](/docs/commands/PSDocs.Dsc/en-US/Invoke-DscNodeDocument.md)
+
+## Changes and versioning
+
+Modules in this repository will use the [semantic versioning](http://semver.org/) model to delcare breaking changes from v1.0.0. Prior to v1.0.0, breaking changes may be introduced in minor (0.x.0) version increments. For a list of module changes please see the [change log](CHANGELOG.md).
 
 ## Maintainers
 
 - [Bernie White](https://github.com/BernieWhite)
 
 ## License
 
-This project is [licensed under the MIT License](LICENSE).
+This project is [licensed under the MIT License](LICENSE).
+
+[psg-psdocs]: https://www.powershellgallery.com/packages/PSDocs

appveyor.yml

@@ -1,4 +1,4 @@
-version: 0.1.0.{build}
+version: 0.3.0.{build}
 image: Visual Studio 2017
 build: off
 test_script:

docs/commands/.markdownlint.json

@@ -0,0 +1,5 @@
+{
+    "first-line-h1": false,
+    "line-length": false,
+    "no-bare-urls": false
+}