Skip to content

Commit 93cc913

Browse files
BernieWhiteBernieWhite
authored
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
1 parent 2e1857f commit 93cc913

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

46 files changed

+1859
-453
lines changed

‎.codecov.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ codecov:
22
notify:
33
require_ci_to_pass: no
44
# dev should be the baseline for reporting
5-
branch: dev
5+
branch: master
66

77
comment:
88
layout: "reach, diff"

‎.gitignore

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,5 @@
66
/build/
77
/reports/
88
/**/*.user
9-
/.vscode/settings.json
9+
/src/**/*-help.xml
10+
/src/**/*.help.txt

‎.vscode/launch.json

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
{
2+
"version": "0.2.0",
3+
"configurations": [
4+
{
5+
"type": "PowerShell",
6+
"request": "launch",
7+
"name": "PowerShell Launch Current File",
8+
"script": "${file}",
9+
"args": [],
10+
"cwd": "${file}"
11+
},
12+
{
13+
"type": "PowerShell",
14+
"request": "launch",
15+
"name": "PowerShell Launch Current File in Temporary Console",
16+
"script": "${file}",
17+
"args": [],
18+
"cwd": "${file}",
19+
"createTemporaryIntegratedConsole": true
20+
},
21+
{
22+
"type": "PowerShell",
23+
"request": "launch",
24+
"name": "PowerShell Launch Current File w/Args Prompt",
25+
"script": "${file}",
26+
"args": [
27+
"${command:SpecifyScriptArgs}"
28+
],
29+
"cwd": "${file}"
30+
},
31+
{
32+
"type": "PowerShell",
33+
"request": "attach",
34+
"name": "PowerShell Attach to Host Process",
35+
"processId": "${command:PickPSHostProcess}",
36+
"runspaceId": 1
37+
},
38+
{
39+
"type": "PowerShell",
40+
"request": "launch",
41+
"name": "PowerShell Interactive Session",
42+
"cwd": "${workspaceRoot}"
43+
}
44+
]
45+
}

‎.vscode/settings.json

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"files.exclude": {
3+
".vs": true,
4+
"artifacts": true,
5+
"reports": true
6+
},
7+
"search.exclude": {
8+
"build": true
9+
}
10+
}

‎.vscode/tasks.json

Lines changed: 29 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
"version": "2.0.0",
55
"tasks": [
66
{
7-
"taskName": "test",
7+
"label": "test",
88
"type": "shell",
99
"command": ".\\scripts\\test.ps1",
1010
"group": {
@@ -14,13 +14,38 @@
1414
"problemMatcher": [ "$pester" ]
1515
},
1616
{
17-
"taskName": "build",
17+
"label": "coverage",
1818
"type": "shell",
19-
"command": ".\\scripts\\build.ps1 -Clean -Module PSDocs",
19+
"command": ".\\scripts\\test.ps1 -Clean -CodeCoverage",
20+
"problemMatcher": [ "$pester" ]
21+
},
22+
{
23+
"label": "build",
24+
"type": "shell",
25+
"command": ".\\scripts\\build.ps1 -Clean -Module PSDocs,PSDocs.Dsc",
2026
"group": {
2127
"kind": "build",
2228
"isDefault": true
23-
}
29+
},
30+
"problemMatcher": []
31+
},
32+
{
33+
"label": "build-docs",
34+
"type": "shell",
35+
"command": ".\\scripts\\build-docs.ps1",
36+
"problemMatcher": []
37+
},
38+
{
39+
"label": "scaffold-docs",
40+
"type": "shell",
41+
"command": ".\\scripts\\build-docs.ps1 -Scaffold",
42+
"problemMatcher": []
43+
},
44+
{
45+
"label": "clean",
46+
"type": "shell",
47+
"command": "Remove-Item -Path .\\build -Recurse -Force",
48+
"problemMatcher": []
2449
}
2550
]
2651
}

‎CHANGELOG.md

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

‎README.md

Lines changed: 78 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,42 @@
11
# PSDocs
2+
23
A PowerShell module with commands to generate markdown from objects using PowerShell syntax.
34

45
| AppVeyor (Windows) | Codecov (Windows) |
56
| --- | --- |
67
| [![av-image][]][av-site] | [![cc-image][]][cc-site] |
78

89
[av-image]: https://ci.appveyor.com/api/projects/status/pl7tu7ktue388n7s
9-
[av-site]: https://ci.appveyor.com/project/BernieWhite/psdocs
10+
[av-site]: https://ci.appveyor.com/project/BernieWhite/PSDocs
1011
[cc-image]: https://codecov.io/gh/BernieWhite/PSDocs/branch/master/graph/badge.svg
1112
[cc-site]: https://codecov.io/gh/BernieWhite/PSDocs
1213

1314
## Disclaimer
15+
1416
This project is to be considered a **proof-of-concept** and **not a supported Microsoft product**.
1517

1618
## Modules
19+
1720
The following modules are included in this repository.
1821

1922
| Module | Description | Latest version |
2023
| ------ | ----------- | -------------- |
21-
| PSDocs | Generate markdown from PowerShell | [v0.2.0][psg-psdocs] |
22-
| PSDocs.Dsc | Extension for PSDocs to generate markdown from Desired State Configuration | [v0.2.0][psg-psdocsdsc] |
24+
| PSDocs | Generate markdown from PowerShell | [v0.3.0][psg-psdocs] |
25+
| PSDocs.Dsc | Extension for PSDocs to generate markdown from Desired State Configuration | [v0.3.0][psg-psdocsdsc] |
2326

2427
[psg-psdocs]: https://www.powershellgallery.com/packages/PSDocs
2528
[psg-psdocsdsc]: https://www.powershellgallery.com/packages/PSDocs.Dsc
2629

2730
## Getting started
2831

29-
### 1. Prerequsits
32+
### Prerequsits
3033

3134
- Windows Management Framework (WMF) 5.0 or greater
3235
- .NET Framework 4.6 or greater
3336

34-
### 2. Get PSDocs
37+
### Getting the modules
3538

36-
- Install from PowerShellGallery.com
39+
- Install from [PowerShell Gallery][psg-psdocs]
3740

3841
```powershell
3942
# Install base PSDocs module
@@ -45,15 +48,26 @@ Install-Module -Name 'PSDocs';
4548
Install-Module -Name 'PSDocs.Dsc';
4649
```
4750

48-
### 3. Usage
51+
- Save for offline use from PowerShell Gallery
52+
53+
```powershell
54+
# Save PSDocs module, in the .\modules directory
55+
Save-Module -Name 'PSDocs' -Path '.\modules';
56+
57+
# Save PSDocs.Dsc module, in the .\modules directory
58+
Save-Module -Name 'PSDocs.Dsc' -Path '.\modules';
59+
```
60+
61+
### Generate a document from a directory listing
4962

5063
```powershell
5164
# Import PSDocs module
5265
Import-Module -Name PSDocs;
5366
54-
# Define a sample document
55-
document Sample {
67+
# Define a document called Sample
68+
Document Sample {
5669
70+
# Add an introduction section
5771
Section Introduction {
5872
# Add a comment
5973
"This is a sample file list from $InputObject"
@@ -63,33 +77,75 @@ document Sample {
6377
}
6478
}
6579
66-
# Call the sample document and generate markdown
67-
Invoke-PSDocument -Name Sample -InputObject 'C:\';
80+
# Call the document definition and generate markdown from an object
81+
Invoke-PSDocument -Name 'Sample' -InputObject 'C:\';
6882
```
6983

70-
For an example of the output generated see [Get-ChildItemExample](/docs/examples/Get-child-item-output.md)
84+
An example of the output generated is available [here](/docs/examples/Get-child-item-output.md).
85+
86+
### Generate documentation from Desired State Configuration
87+
88+
```powershell
89+
# Import PSDocs.Dsc module
90+
Import-Module -Name PSDocs.Dsc;
91+
92+
# Define a document called Sample
93+
Document 'Sample' {
94+
95+
# Add an 'Installed features' section in the document
96+
Section 'Installed features' {
97+
# Add a comment
98+
'The following Windows features have been installed.'
99+
100+
# Generate a table of Windows Features
101+
$InputObject.ResourceType.WindowsFeature | Table -Property Name,Ensure
102+
}
103+
}
104+
105+
# Call the document definition and generate markdown for each .mof file in the .\nodes directory
106+
Invoke-DscNodeDocument -DocumentName 'Sample' -Path '.\nodes' -OutputPath '.\docs';
107+
```
71108

72109
## Language reference
73110

111+
PSDocs extends PowerShell with domain specific lanagage (DSL) keywords and cmdlets.
112+
74113
### Keywords
75114

76-
- [Document](/docs/keywords/Document.md)
77-
- [Section](/docs/keywords/Section.md)
78-
- [Code](/docs/keywords/Code.md)
79-
- [Note](/docs/keywords/Note.md)
80-
- [Warning](/docs/keywords/Warning.md)
81-
- [Yaml](/docs/keywords/Yaml.md)
82-
- [Table](/docs/keywords/Table.md)
115+
The following language keywords are used by the `PSDocs` module:
116+
117+
- [Document](/docs/keywords/PSDocs/en-US/Document.md) - Defines a named documentation block
118+
- [Section](/docs/keywords/PSDocs/en-US/Section.md) - Creates a named section
119+
- [Title](/docs/keywords/PSDocs/en-US/Title.md) - Sets the document title
120+
- [Code](/docs/keywords/PSDocs/en-US/Code.md) - Inserts a block of code
121+
- [Note](/docs/keywords/PSDocs/en-US/Note.md) - Inserts a note using DocFx formatted markdown (DFM)
122+
- [Warning](/docs/keywords/PSDocs/en-US/Warning.md) - Inserts a warnding usinf DocFx formatted markdown (DFM)
123+
- [Yaml](/docs/keywords/PSDocs/en-US/Yaml.md) - Inserts a YAML header
124+
- [Table](/docs/keywords/PSDocs/en-US/Table.md) - Inserts a table from pipeline objects
83125

84126
### Commands
85127

86-
- [Invoke-PSDocument](/docs/commands/Invoke-PSDocument.md)
87-
- [Invoke-DscNodeDocument](/docs/commands/Invoke-DscNodeDocument.md)
128+
The following commands exist in the `PSDocs` module:
129+
130+
- [Invoke-PSDocument](/docs/commands/PSDocs/en-US/Invoke-PSDocument.md)
131+
- [Get-PSDocumentHeader](/docs/commands/PSDocs/en-US/Get-PSDocumentHeader.md)
132+
- [Import-PSDocumentTemplate](/docs/commands/PSDocs/en-US/Import-PSDocumentTemplate.md)
133+
134+
The following commands exist in the `PSDocs.Dsc` module:
135+
136+
- [Get-DscMofDocument](/docs/commands/PSDocs.Dsc/en-US/Get-DscMofDocument.md)
137+
- [Invoke-DscNodeDocument](/docs/commands/PSDocs.Dsc/en-US/Invoke-DscNodeDocument.md)
138+
139+
## Changes and versioning
140+
141+
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).
88142

89143
## Maintainers
90144

91145
- [Bernie White](https://github.com/BernieWhite)
92146

93147
## License
94148

95-
This project is [licensed under the MIT License](LICENSE).
149+
This project is [licensed under the MIT License](LICENSE).
150+
151+
[psg-psdocs]: https://www.powershellgallery.com/packages/PSDocs

‎appveyor.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
version: 0.1.0.{build}
1+
version: 0.3.0.{build}
22
image: Visual Studio 2017
33
build: off
44
test_script:

‎docs/commands/.markdownlint.json

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"first-line-h1": false,
3+
"line-length": false,
4+
"no-bare-urls": false
5+
}

‎docs/commands/Invoke-DscNodeDocument.md

Lines changed: 0 additions & 30 deletions
This file was deleted.

0 commit comments

Comments
 (0)