Commit 1ad352f5 authored by Laurent Sittler's avatar Laurent Sittler ©

First commit

parent aaf926b6
## Ignore Visual Studio temporary files, build results, and
## files generated by popular Visual Studio add-ons.
##
## Get latest from https://github.com/github/gitignore/blob/master/VisualStudio.gitignore
# User-specific files
*.suo
*.user
*.userosscache
*.sln.docstates
# OSX
.DS_Store
# Windows
Thumbs.db
# User-specific files (MonoDevelop/Xamarin Studio)
*.userprefs
# Build results
[Dd]ebug/
[Dd]ebugPublic/
[Rr]elease/
[Rr]eleases/
x64/
x86/
bld/
[Bb]in/
[Oo]bj/
[Ll]og/
# Visual Studio 2015 cache/options directory
.vs/
# Uncomment if you have tasks that create the project's static files in wwwroot
#wwwroot/
# MSTest test Results
[Tt]est[Rr]esult*/
[Bb]uild[Ll]og.*
# NUNIT
*.VisualState.xml
TestResult.xml
# Build Results of an ATL Project
[Dd]ebugPS/
[Rr]eleasePS/
dlldata.c
# .NET Core
project.lock.json
project.fragment.lock.json
artifacts/
**/Properties/launchSettings.json
*_i.c
*_p.c
*_i.h
*.ilk
*.meta
*.obj
*.pch
*.pdb
*.pgc
*.pgd
*.rsp
*.sbr
*.tlb
*.tli
*.tlh
*.tmp
*.tmp_proj
*.log
*.vspscc
*.vssscc
.builds
*.pidb
*.svclog
*.scc
# Chutzpah Test files
_Chutzpah*
# Visual C++ cache files
ipch/
*.aps
*.ncb
*.opendb
*.opensdf
*.sdf
*.cachefile
*.VC.db
*.VC.VC.opendb
# Visual Studio profiler
*.psess
*.vsp
*.vspx
*.sap
# TFS 2012 Local Workspace
$tf/
# Guidance Automation Toolkit
*.gpState
# ReSharper is a .NET coding add-in
_ReSharper*/
*.[Rr]e[Ss]harper
*.DotSettings.user
# JustCode is a .NET coding add-in
.JustCode
# TeamCity is a build add-in
_TeamCity*
# DotCover is a Code Coverage Tool
*.dotCover
# Visual Studio code coverage results
*.coverage
*.coveragexml
# NCrunch
_NCrunch_*
.*crunch*.local.xml
nCrunchTemp_*
# MightyMoose
*.mm.*
AutoTest.Net/
# Web workbench (sass)
.sass-cache/
# Installshield output folder
[Ee]xpress/
# DocProject is a documentation generator add-in
DocProject/buildhelp/
DocProject/Help/*.HxT
DocProject/Help/*.HxC
DocProject/Help/*.hhc
DocProject/Help/*.hhk
DocProject/Help/*.hhp
DocProject/Help/Html2
DocProject/Help/html
# Click-Once directory
publish/
# Publish Web Output
*.[Pp]ublish.xml
*.azurePubxml
# TODO: Comment the next line if you want to checkin your web deploy settings
# but database connection strings (with potential passwords) will be unencrypted
*.pubxml
*.publishproj
# Microsoft Azure Web App publish settings. Comment the next line if you want to
# checkin your Azure Web App publish settings, but sensitive information contained
# in these scripts will be unencrypted
PublishScripts/
# NuGet Packages
*.nupkg
# The packages folder can be ignored because of Package Restore
**/packages/*
# except build/, which is used as an MSBuild target.
!**/packages/build/
# Uncomment if necessary however generally it will be regenerated when needed
#!**/packages/repositories.config
# NuGet v3's project.json files produces more ignorable files
*.nuget.props
*.nuget.targets
# Microsoft Azure Build Output
csx/
*.build.csdef
# Microsoft Azure Emulator
ecf/
rcf/
# Windows Store app package directories and files
AppPackages/
BundleArtifacts/
Package.StoreAssociation.xml
_pkginfo.txt
# Visual Studio cache files
# files ending in .cache can be ignored
*.[Cc]ache
# but keep track of directories ending in .cache
!*.[Cc]ache/
# Others
ClientBin/
~$*
*~
*.dbmdl
*.dbproj.schemaview
*.jfm
*.pfx
*.publishsettings
orleans.codegen.cs
# Since there are multiple workflows, uncomment next line to ignore bower_components
# (https://github.com/github/gitignore/pull/1529#issuecomment-104372622)
#bower_components/
# RIA/Silverlight projects
Generated_Code/
# Backup & report files from converting an old project file
# to a newer Visual Studio version. Backup files are not needed,
# because we have git ;-)
_UpgradeReport_Files/
Backup*/
UpgradeLog*.XML
UpgradeLog*.htm
# SQL Server files
*.mdf
*.ldf
*.ndf
# Business Intelligence projects
*.rdl.data
*.bim.layout
*.bim_*.settings
# Microsoft Fakes
FakesAssemblies/
# GhostDoc plugin setting file
*.GhostDoc.xml
# Node.js Tools for Visual Studio
.ntvs_analysis.dat
node_modules/
# Typescript v1 declaration files
typings/
# Visual Studio 6 build log
*.plg
# Visual Studio 6 workspace options file
*.opt
# Visual Studio 6 auto-generated workspace file (contains which files were open etc.)
*.vbw
# Visual Studio LightSwitch build output
**/*.HTMLClient/GeneratedArtifacts
**/*.DesktopClient/GeneratedArtifacts
**/*.DesktopClient/ModelManifest.xml
**/*.Server/GeneratedArtifacts
**/*.Server/ModelManifest.xml
_Pvt_Extensions
# Paket dependency manager
.paket/paket.exe
paket-files/
# FAKE - F# Make
.fake/
# JetBrains Rider
.idea/
*.sln.iml
# CodeRush
.cr/
# Python Tools for Visual Studio (PTVS)
__pycache__/
*.pyc
# Cake - Uncomment if you are using it
# tools/**
# !tools/packages.config
# Telerik's JustMock configuration file
*.jmconfig
# BizTalk build output
*.btp.cs
*.btm.cs
*.odx.cs
*.xsd.cs
<#
.SYNOPSIS
Generates Markdown documentation for PowerShell Script- or Modulefiles.
.DESCRIPTION
Script to automatically generate Markdown documentation for PowerShell Scripts and modules. Uses EPS (Embedded PowerShell) for templating.
.PARAMETER scriptFile
Specifies the path to the script or module file.
.PARAMETER outputFile
Specifies the path to the markdown output file.
.PARAMETER template
Specifies the path to the markdown template file.
.INPUTS
None. You cannot pipe objects to Update-Month.ps1.
.OUTPUTS
None. Update-Month.ps1 does not generate any output.
.EXAMPLE
C:\PS> Invoke-MdDocs -outputFile 'C:\temp\out.md' -scriptFile 'C:\temp\script.ps1'
.LINK
https://github.com/itpropro/PsDocGen
#>
param
(
[parameter(Mandatory = $true)]
[string]$scriptFile,
[parameter(Mandatory = $true)]
[string]$outputFile,
[parameter(Mandatory = $false)]
[string]$template = ".\md.eps"
)
if (-not (Test-Path $scriptFile))
{
Write-Error 'Scriptfile not found. Exiting...'
exit
}
$global:CommandDirectory = Split-Path $SCRIPT:MyInvocation.MyCommand.Path -Parent
if (-not (Get-Module -Name EPS))
{
$EPSModule = Join-Path -Path $global:CommandDirectory -ChildPath "references\EPS\EPS.psd1"
Import-Module $EPSModule
}
# Get the AST of the file
$tokens = $errors = $null
$ast = [System.Management.Automation.Language.Parser]::ParseFile(
$scriptFile,
[ref]$tokens,
[ref]$errors)
$header = Invoke-Command {
if ($ast.GetHelpContent())
{
$commentBlock = $ast.GetHelpContent().GetCommentBlock()
}
else
{
$commentBlock = [System.Management.Automation.Language.CommentHelpInfo]::new()
}
$scriptBlock = [scriptblock]::Create(('
function {0} {{
{1}
{2}
}}' -f (Get-Item $scriptFile).Name, $commentBlock, $ast.ParamBlock.Extent.Text))
& {
. $scriptBlock
Get-Help (Get-Item $scriptFile).Name
}
}
# Get only function definition ASTs
$functionDefinitions = $ast.FindAll(
{
param(
[System.Management.Automation.Language.Ast] $Ast
)
$Ast -is [System.Management.Automation.Language.FunctionDefinitionAst] -and ($PSVersionTable.PSVersion.Major -lt 5 -or $Ast.Parent -isnot [System.Management.Automation.Language.FunctionMemberAst])
}, $true)
$helpContent = $functionDefinitions | ForEach-Object {
if ($_.GetHelpContent())
{
$commentBlock = $_.GetHelpContent().GetCommentBlock()
}
else
{
$commentBlock = ''
}
$scriptBlock = [scriptblock]::Create(('
function {0} {{
{1}
{2}
}}' -f $_.Name, $commentBlock, $_.Body.ParamBlock.Extent.Text))
& {
. $scriptBlock
Get-Help $_.Name
}
}
# Manually generate syntax from function parameter objects to handle functions without help header
$i = 0
foreach ($function in $helpContent)
{
$syntax = ''
foreach ($item in $function.Syntax.SyntaxItem)
{
$syntax += $item.name
foreach ($parameter in ($item.parameter))
{
if ($parameter.required -eq 'true')
{
$syntax += ' [-{0}]{1}' -f $parameter.name, (. ($({" <$($parameter.parameterValue)>"}), {})[!$parameter.parameterValue])
}
else
{
$syntax += ' [[-{0}{1}]' -f $parameter.name, (. ($({" <$($parameter.parameterValue)>"}), {})[!$parameter.parameterValue])
}
}
if (([System.String]::IsNullOrEmpty($function.Syntax.syntaxItem.count)) -or ($function.Syntax.syntaxitem[$function.Syntax.syntaxItem.count - 1] -eq $item))
{
$syntax += " [<CommonParameters>]"
}
else
{
$syntax += " [<CommonParameters>]`n"
}
}
$helpContent[$i].Syntax = $syntax
$i++
}
Invoke-EpsTemplate -Path .\md.eps -Safe -Binding @{header = $header; helpContent = $helpContent} | Out-File $outputFile
\ No newline at end of file
# PsDocGen
Based on: https://github.com/itpropro/PsDocGen
\ No newline at end of file
Script to automatically generate Markdown documentation for PowerShell Scripts and modules. Uses EPS (Embedded PowerShell) for templating.
## Syntax
```PowerShell
Invoke-MdDocs.ps1 [-outputFile] <String> [-scriptFile] <String> [[-template] <String>]
```
## Description
Script to automatically generate Markdown documentation for PowerShell Scripts and modules. Uses EPS ( Embedded PowerShell) for templating.
## Examples
### Example 1
```PowerShell
.\Invoke-MdDocs -outputFile 'C:\temp\out.md' -scriptFile 'C:\temp\script.ps1'
```
### Example 2
```PowerShell
.\Invoke-MdDocs -outputFile 'C:\temp\out.md' -scriptFile 'C:\temp\script.ps1' -template 'custom-md.eps'
```
## Related links
* https://github.com/itpropro/PsDocGen
# <%= $header.name %>
<% if ( $header.description.text) { -%>
## Description
<%= $header.description.text %>
<% } -%>
<% if ( $header.parameters.parameter) { %>
## Parameters
| Name | Alias | Description | Required? | Pipeline Input | Default Value |
| --- | --- | --- | --- | --- | --- |
<% $header.parameters.parameter | % { -%>
| <%= $_.Name %> | <%= $_.Aliases %> | <%= ($_.Description | out-string).Trim() %> | <%= $_.Required %> | <%= $_.PipelineInput %> | <%= $_.DefaultValue %> |
<% } -%>
<% } -%>
---
## Functions:
<% $helpContent | Foreach-Object { -%>
## <%= $_.Name %>
### Synopsis
<%= $_.synopsis.Trim() %>
### Syntax
``````powershell
<%= $_.syntax %>
``````
### Parameters
| Name | Alias | Description | Required? | Pipeline Input | Default Value |
| --- | --- | --- | --- | --- | --- |
<% $_.parameters.parameter | % { -%>
| <%= $_.Name %> | <%= $_.Aliases %> | <%= ($_.Description | out-string).Trim() %> | <%= $_.Required %> | <%= $_.PipelineInput %> | <%= $_.DefaultValue %> |
<% } -%>
<% if ($_.inputtypes.inputtype.type.name) { -%>
### Inputs
- <%= $_.inputtypes.inputtype.type.name %>
<% } -%>
<% if ( $_.returnvalues.returnvalue.type.name) { %>
### Outputs
- <%= $_.returnvalues.returnvalue.type.name -%>
<% } -%>
<% if ($_.alertSet) { -%>
### Notes
<%= $_.alertSet | out-string %>
<% } -%>
<%= $isExamples = (($_.examples | Out-String).Trim().length -gt 0) %>
<% if ($isExamples) { -%>
### Examples
**<%= $_.examples.example.title.replace(`"-`",`"`").trim() -%>**
``````powershell
<%= $_.examples.example.code | out-string -%>
``````
<% } -%>
<% if ($_.relatedLinks) { -%>
### Links
<%= $_.relatedLinks -%>
<% } -%>
<% } -%>
\ No newline at end of file
@{
# Script module or binary module file associated with this manifest.
ModuleToProcess = 'EPS.psm1' # using ModuleToProcess for PS 2.0 compatibility
# Version number of this module.
ModuleVersion = '1.0.0'
# ID used to uniquely identify this module
GUID = 'f24c1ca7-e4fd-4b7d-8ff8-75ef7f7ea162'
# Author of this module
Author = 'Dave Wu, Dominique Broeglin'
# Copyright statement for this module
Copyright = '(c) 2014 Dave Wu. All rights reserved.'
# Description of the functionality provided by this module
Description = @'
EPS (Embedded PowerShell), inspired by ERB (see https://en.wikipedia.org/wiki/ERuby), is a templating language that embeds PowerShell code into a text document. It is conceptually and syntactically similar to ERB for Ruby or Twig (see http://twig.sensiolabs.org/) for PHP.
EPS can be used to generate any kind of text. The example below illustrates generating plain text, but it could be used to generate HTML in a web application or PowerShell code as in the Forge Module generator (see https://github.com/dbroeglin/Forge.Module)
'@
# Minimum version of the Windows PowerShell engine required by this module
# PowerShellVersion = ''
# Name of the Windows PowerShell host required by this module
# PowerShellHostName = ''
# Minimum version of the Windows PowerShell host required by this module
# PowerShellHostVersion = ''
# Minimum version of Microsoft .NET Framework required by this module
# DotNetFrameworkVersion = ''
# Minimum version of the common language runtime (CLR) required by this module
# CLRVersion = ''
# Processor architecture (None, X86, Amd64) required by this module
# ProcessorArchitecture = ''
# Modules that must be imported into the global environment prior to importing this module
# RequiredModules = @()
# Assemblies that must be loaded prior to importing this module
# RequiredAssemblies = @()
# Script files (.ps1) that are run in the caller's environment prior to importing this module.
# ScriptsToProcess = @()
# Type files (.ps1xml) to be loaded when importing this module
# TypesToProcess = @()
# Format files (.ps1xml) to be loaded when importing this module
# FormatsToProcess = @()
# Modules to import as nested modules of the module specified in RootModule/ModuleToProcess
# NestedModules = @()
# Functions to export from this module
FunctionsToExport = 'Invoke-EpsTemplate'
# Cmdlets to export from this module
CmdletsToExport = '*'
# Variables to export from this module
VariablesToExport = '*'
# Aliases to export from this module
AliasesToExport = '*'
# List of all modules packaged with this module
# ModuleList = @()
# List of all files packaged with this module
# FileList = @()
# Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.
PrivateData = @{
PSData = @{
# Tags applied to this module. These help with module discovery in online galleries.
Tags = 'PowerShell', 'Template'
# A URL to the license for this module.
LicenseUri = 'https://opensource.org/licenses/MIT'
# A URL to the main website for this project.
ProjectUri = 'https://github.com/straightdave/eps'
# A URL to an icon representing this module.
# IconUri = ''
# ReleaseNotes of this module
# ReleaseNotes = ''
} # End of PSData hashtable
} # End of PrivateData hashtable
# HelpInfo URI of this module
# HelpInfoURI = ''
# Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix.
# DefaultCommandPrefix = ''
}
#######################################################
##
## EPS - Embedded PowerShell
## Dave Wu, June 2014
##
## Templating tool for PowerShell
## For detailed usage please refer to:
## http://straightdave.github.io/eps
##
#######################################################
# Load functions
$functions = Get-ChildItem -Path $PSScriptRoot -Recurse -Include *.ps1 |
Sort-Object |
ForEach-Object { . $_.FullName }