Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ismaelw/ps-documentor
Automatic PowerShell Function Documenting
https://github.com/ismaelw/ps-documentor
Last synced: 3 months ago
JSON representation
Automatic PowerShell Function Documenting
- Host: GitHub
- URL: https://github.com/ismaelw/ps-documentor
- Owner: ismaelw
- License: mit
- Created: 2021-05-25T14:07:57.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2021-06-09T10:32:34.000Z (over 3 years ago)
- Last Synced: 2024-05-02T03:16:04.720Z (9 months ago)
- Language: PowerShell
- Size: 15.6 KB
- Stars: 14
- Watchers: 2
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: Readme.md
- License: LICENSE
Awesome Lists containing this project
README
# Automatic PowerShell Script Documentor
This Script can be used to document all Custom PowerShell Functions inside of a Script or a Script Directory.
I just created this script and I am testing it to multiple use cases. This whole project could be a PowerShell module in the future.
For now I just want to have it sitting here and enhance it.
An example documentation generated for this script can be found inside the `Output` folder.
## Usage
See the `New-ScriptDocumentation` function below for how to use this Script. You Basically have two options:
- Create one documentation file for all functions in all provided script files or one documentation for a single script file provided
- Create multiple documentation files for each script file provided
## Contents
- [New-ScriptDocumentation](#new-scriptdocumentation)
## New-ScriptDocumentation
### Syntax
```
New-ScriptDocumentation -Folder -FileTypes [-Output ] [-Assemblies ] [-Destination ] []
New-ScriptDocumentation -File [-Assemblies ] [-Destination ] []
```
### Synopsis
Script that automatically creates Markdown Documentations for all functions inside a script file or inside of multiple scripts in a folder.
### Description
Script that automatically creates Markdown Documentations for all functions inside a script file or inside of multiple scripts in a folder. This works by parsing the script files and just exporting all functions. The temporary function file can then be dot-sourced to make all functions available to the console.
In the console this script can use Get-Help and Get-Command to get all details to each function.
### Examples
#### Example 1
`New-ScriptDocumentation -File 'C:\Scripts\ProjectOne\Script.ps1'`
Creates a Markdown Documentation for all functions inside one Scriptfile.
#### Example 2
`New-ScriptDocumentation -File 'C:\Scripts\ProjectOne\Script.ps1' -Destination 'C:\Temp\'`
Creates a Markdown Documentation for all functions inside one Scriptfile. The documentation will be saved inside C:\Temp.
#### Example 3
`New-ScriptDocumentation -Folder 'C:\Scripts\ProjectOne' -FileTypes '.ps1','.psm' -Destination 'C:\Temp\'`
Creates a Markdown Documentation for each script files inside of a folder. The documentations will be saved inside C:\Temp.
#### Example 4
`New-ScriptDocumentation -Folder 'C:\Scripts\ProjectOne' -FileTypes '.ps1','.psm' -Output 'Single' -Assemblies 'System.Windows.Forms', 'System.Drawing' -Destination 'C:\Temp\'`
Creates one Markdown Documentation for all script files inside of a folder. The Script uses two Assemblies that are loaded while processing each script file. The single documentation will be saved inside C:\Temp.
### Parameters
`-Folder`
The path to the folder containing multiple script files that needs to be documented.
Typestring
Is MandatoryTrue
Aliases
Accept pipeline inputFalse
`-FileTypes`
An array of extensions to select which files should be documented recursively.
Typestring[]
Is MandatoryTrue
Aliases
Accept pipeline inputFalse
`-Output`
Single or Multi - Defines whether only one documentation should be created or one per script file.
Typestring
Is MandatoryFalse
Aliases
Accept pipeline inputFalse
`-Destination`
Defines where the documentation files are beeing saved.
Typestring
Is MandatoryFalse
Aliases
Accept pipeline inputFalse
`-File`
The path to the script file that needs to be documented.
Typestring
Is MandatoryTrue
Aliases
Accept pipeline inputFalse
`-Assemblies`
An array of assemblies needed by the script
Typestring[]
Is MandatoryFalse
Aliases
Accept pipeline inputFalse
# Development Roadmap
- [x] Possibility to add Assembly Names
- [x] Possibility to create multiple documentation files for each Script or a single documentation containing all of them
- [x] Add Description and Synopsis to Documentation
- [x] Export defined examples
- [x] Print relative path to script file instead of absolute path
- [x] Figure out how to deal with duplicate attributes beeing documented when using multiple parameter sets
- [ ] Find a way to automatically parse script files to find all assemblies