8000 Added files that where removed when rebuilding. Updated documentation · ModuleBuild/ModuleBuild@615327a · GitHub
[go: up one dir, main page]
Skip to content

Commit 615327a

Browse files
justin-pjustin-p
committed
Added files that where removed when rebuilding. Updated documentation
1 parent 75e6dc7 commit 615327a

Some content is hidden

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

42 files changed

+842
-58
lines changed

‎ModuleBuild.psd1

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,16 +24,16 @@ GUID = '2b53a392-3b0f-4a7c-b934-7c995252070e'
2424
Author = 'Zachary Loeber'
2525

2626
# Company or vendor of this module
27-
CompanyName = ' '
27+
# CompanyName = ' '
2828

2929
# Copyright statement for this module
30-
Copyright = '(c) 2020 . All rights reserved.'
30+
Copyright = '(c) 2020 Zachary Loeber. All rights reserved.'
3131

3232
# Description of the functionality provided by this module
3333
Description = 'A scaffolding framework which can be used to kickstart a generic PowerShell module project. '
3434

3535
# Minimum version of the Windows PowerShell engine required by this module
36-
# PowerShellVersion = ''
36+
PowerShellVersion = '5.0.0'
3737

3838
# Name of the Windows PowerShell host required by this module
3939
# PowerShellHostName = ''

‎build/docs/Additional/Acknowledgements.md

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,16 @@
22

33
Project Site: [https://github.com/zloeber/ModuleBuild](https://github.com/zloeber/ModuleBuild)
44

5-
This project owes some acknowledgements to other projects. Here are some other authors or projects which have made this project possible. If you believe you or a project should be included in this list please let us know.
5+
This project owes some acknowlegement to other projects. Here are some other authors or projects which have made this project possible. If you believe you or a project should be included in this list please let us know.
66

7-
[ModuleBuild](https://github.com/zloeber/ModuleBuild) - A PowerShell module build framework.
7+
[Invoke-Build](https://github.com/nightroman/Invoke-Build) - A kick ass build automation tool written in PowerShell. It is the primary engine behind this little project.
8+
9+
[Plaster](https://github.com/PowerShell/Plaster) - Used for the code scaffolding portion of this project.
10+
11+
[PSCodeHealth](https://github.com/MathieuBuisson/PSCodeHealth) - PowerShell code health reporting.
12+
13+
[Hitchhikers Guide to the PowerShell Pipeline](https://xainey.github.io/2017/powershell-module-pipeline/)
14+
15+
[Write the Faq'n Manual](https://get-powershellblog.blogspot.com/2017/03/write-faq-n-manual-part1.html)
16+
17+
[PowerShell Practice and Style](https://github.com/PoshCode/PowerShellPracticeAndStyle) - Great site to read over to learn everything you are needing to do to up your game in PowerShell.

‎build/docs/Additional/ChangeLog.md

Lines changed: 87 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,91 @@
22

33
Project Site: [https://github.com/zloeber/ModuleBuild](https://github.com/zloeber/ModuleBuild)
44

5-
## Version 0.3.0
5+
## Version 0.2.3
6+
- Added ability to pull in some basic information about an existing module manifest files when running initialize-modulebuild.
7+
- Fixed ReadTheDocs generation issues by updating the template to include build\docs\ReadTheDocs in the initialization process.
8+
- Eliminated any customization requirements within the modulename.build.ps1 script to help pave the way for easier modulebuild upgrades to projects.
9+
- Removed some superfluous code in the base build environment script around the RequiredModules variable.
10+
## Version 0.2.2
11+
- Updated vscode tasks.json to fix depreciated syntax.
12+
- Fixed `-Force` switch processing on Add-PublicFunction to still create the function if the provided name is detected as plural.
13+
- Fixed [cleanup script modulebuild execution issue](https://github.com/zloeber/ModuleBuild/issues/5) by separating out the postbuildtask into its own Invoke-Build code block (I had done this a while ago and never rolled up the changes into the Plaster template).
14+
- Fixed a glaring issue with the PlatyPS output where any Guids were 00000000-0000-0000-0000-000000000000 instead of the actual module manifest Guid [reported via issue #6](https://github.com/zloeber/ModuleBuild/issues/6). This happens because we build the module help from the psm1 load of the module in memory, not the psd1 file as that psd1 manifest gets recreated at build time with the appropriate exported functions and such. Basically a chicken/egg scenario. For now we just manually replace the output markdown files with the correct Guid before moving on to the help file packaging.
15+
16+
## Version 0.2.1
17+
- Merged pull request #3 to resolve initialization issues for new modules in directories with spaces in their path.
18+
- Added additional github integration (via .github folder creation with pull and issue template markdown files)
19+
- Fixed improper spelling of 'license' in license creation templating.
20+
21+
## Version 0.1.10
22+
- Fixed the -AddCBH build task.
23+
- Fixed the missing documentation platyps output to show the actual found line that indicates missing CBH.
24+
25+
## Version 0.1.9
26+
- Removed plaster option to choose to combine the module source at build time (and simply made that behavior the default that can be changed later via Set-MBTBuildEnvironment -OptionCombineFiles $false)
27+
- Added option to run a code health report (via PSCodeHealth) against your public and private function directories prior to starting the build
28+
- Added 'Module plugin' capability. This adds base functionality to the module project itself. The first included module plugin is the nlogmodule logging functionality.
29+
30+
## Version 0.1.6
31+
- Added New-PublicFunction to module along with a template folder and basic function template to start with. Any src\templates\\\<template_name\>.tem file is able to be used for this new feature and any build environment variable surrounded by double percentage symbols will be automatically replaced (ie. %%ModuleName%%).
32+
- Fixed ReadTheDocs yml creation issue with the licensing link.
33+
34+
## Version 0.1.5
35+
- Fixed awful .gitignore settings included in the default scaffolding
36+
- Fixed documentation links to be self-referencing
37+
- Removed AdditionalModulePaths from initial plaster manifest (can just set this with Set-MBTBuildEnvironment after creation)
38+
39+
## Version 0.1.4
40+
- Fixed invalid mkdocs.yml license link reference
41+
- Fixed invalid reference to acknowledgements folder in plaster manifest (thanks Roberto Desideri!)
42+
43+
## Version 0.1.3
44+
- Fixes to mkdocs.yml formatting
45+
- Fixed temp build directory exclusion in .gitignore file
46+
47+
## Version 0.1.2
48+
- Updated vs code task names
49+
- Fixed an issue with a null build environment variable causing dynamic parameters in Set-MBTBuildEnvironment to fail
50+
- Several small scaffolding clean ups.
51+
52+
## Version 0.1.1
53+
- Removed prompts for the nuget api key when running initialize-modulebuild.
54+
- Initialize-ModuleBuild now automatically runs the build environment powershell script for the first time to create the modulebuild json settings file.
55+
- More documentation.
56+
- Fixed some minor scaffolding creation issues.
57+
- Added a 'ForceInstallModule' setting to eliminate build prompt when running the install and test module build tasks when the module is already installed.
58+
- Fixed VS Code tasks.
59+
- Added additional VS Code tasks when pressing ctrl+shift+B.
60+
- Added two new public functions for importing public/private functions from existing modules to a modulebuild project.
61+
- Added setting 'OptionUpdateVersionAfterPublishing' to ensure that this gets done after publishing to the gallery.
62+
- Fixed initial sensitive term settings generation to work on non-domain joined machines.
63+
64+
## Version 0.0.6
65+
- Changed all template files from .ps1 or psm1 to .template and changed the plaster manifest accordingly
66+
- Change all .<filename> files to remove the period so uploads to the gallery will work properly
67+
- Combined the UpdateRelease and NewVersion tasks and made both promptable
68+
- Fixed git version tag issue with the build script for the plaster manifest file.
69+
- Removed options to prompt for different folder names (like public/private/other/temp) and updated all template files and plaster manifest file accordinly.
70+
71+
## Version 0.0.5
72+
- fixes to plaster template creation
73+
74+
## Version 0.0.4
75+
- fixes to psgallery upload
76+
77+
## Version 0.0.3
78+
- Eliminated all '-Before' and '-After' in task definitions
79+
- Added 'Write-Description' helper function and converted all write-build lines to use it instead (for a quick indented output that is easier on the eyes)
80+
- Eliminated a large number of global variables in favor of simply redefining them in local tasks when required
81+
- Setup readthedocs.net yml file generation to fail with warning if the file already exists.
82+
- Fixed the version check to automatically fail if the build you are running already exists in the powershell gallery.
83+
- Applied the -force flag to several tasks where it made sense to do so (need to manually build with Invoke-Build and the -force parameter to use)
84+
- Fixed up Visual Studio Code tasks.json settings
85+
- Added a prebuild folder for processing dependant/separate scripts prior to starting your build
86+
- Updated much of the documentation.
87+
88+
## Version 0.0.2
89+
- Structural changes
90+
91+
## Version 0.0.1
692
- Initial release

‎build/docs/Additional/Contributing.md

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,16 +5,18 @@ Project Site: [https://github.com/zloeber/ModuleBuild](https://github.com/zloebe
55
There are some important things to be aware of if you plan on contributing to this project.
66

77
## Documentation
8-
All base project documentation changes should be made against the .\build\docs\Additional markdown files. These will populate and overwrite existing document files within the .\docs folder at build time. Additionally, if ReadTheDocs integration is enabled you should update the .\build\docs\ReadTheDocs markdown files. Note that each folder becomes its own section within ReadTheDocs and its own folder within the .\docs directory.
8+
All base project documentation changes should be made against the .\build\docs\Additional markdown files. These will populate and overwrite existing document files within the .\docs folder at build time. Additionally, you should update the .\build\docs\ReadTheDocs markdown files. Note that each folder becomes its own section within ReadTheDocs and its own folder within the .\docs directory.
99

1010
Finally, the Function documentation gets generated automatically based on the comment based help on each public/exported function. The function documentation markdown automatically gets populated within the .\docs\Functions folder as well as with the module release under its own docs folder. Private function CBH is not required but is encouraged.
1111

1212
## Development Environment
13-
While any text editor will work well there are included task and setting json files explicitly for Visual Studio Code included with this project. The following tasks have been defined to make things a bit easier. First access the 'Pallette' (Shift+Ctrl+P or Shift+Cmd+P) and start typing in any of the following tasks to find and run them:
13+
While any text editor will work well there are included task and setting json files explicitly for Visual Studio Code included with this project. I used VS Code Insiders edition but standard edition should be fine as well. The following tasks have been defined to make things a bit easier. First access the 'Pallette' (Shift+Ctrl+P or Shift+Cmd+P) and start typing in any of the following tasks to find and run them:
1414

15-
- Clean -> Cleans out your scratch folder
1615
- Build -> Runs the Build task (also can use Shift+Ctrl+B or Shift+Cmd+B)
1716
- Analyze -> Runs PSScriptAnalyzer against the src/public files.
1817
- CreateProjectHelp - Creates the project level help.
19-
- Test - Runs Pester tests.
2018
- AddMissingCBH - Analyzes the existing public functions and inserts a template CBH if no CBH already exists and saves it into your scratch folder.
19+
20+
The plaster manifest file gets automatically recreated at build time so all you need to do is update the plasterparams.ps1 and/or plastercontent.ps1 in the plaster directory to include any required changes you need to make.
21+
22+
The plaster scaffolding files are largely standard files. But there are some template exceptions that you should be careful not to overwrite (any of the files that dynamically replace content from plaster input at creation time).

‎build/docs/Additional/ToDo.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# ModuleBuild ToDo List
2+
3+
Project Site: [https://github.com/zloeber/ModuleBuild](https://github.com/zloeber/ModuleBuild)
4+
5+
There are many items which are possible and should probably be added to this project. Here are a few thoughts on ones I'll probably get addressed sooner or later. I'm open to suggestions or pull requests.
6+
7+
- Update the sensitive parameter scans to be a pester test instead
8+
- Add pre-gallary deployment pester tests for any files that will cause issues or cause the psscript analyzer at the gallery to fail (so files beginning with a period will not transfer, ps1 files in extra directories will cause analyzer failures, et cetera)
9+
- ~~Create functions to pull functions from another module (function only) and recreate them in the current module project directory would be cool.~~
10+
- Better git tasks?
11+
- Include more useful base pester tests for standard modules
12+
- ~~Automatic module version update options if uploading to the gallery~~
13+
- Automatic clean up of additional loaded modules when uploading to the gallery
14+
- Powershell Core compatibility
15+
- Automatic updates of the ReleaseNotes.md file
16+
- Appveyor integration?
17+
- PSDeploy integration?
18+
- Github releases integration?
19+
- Smoother path to upgrade ModuleBuild for existing projects

‎build/docs/Additional/index.md

Lines changed: 20 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,28 @@
11
# ModuleBuild
2-
A scaffolding framework which can be used to kickstart a generic PowerShell module project.
2+
A scaffolding framework which can be used to kickstart a generic PowerShell module project.
33

44
Project Site: [https://github.com/zloeber/ModuleBuild](https://github.com/zloeber/ModuleBuild)
55

66
## What is ModuleBuild?
7-
A scaffolding framework which can be used to kickstart a generic PowerShell module project.
7+
A scaffolding framework which can be used to kickstart a generic PowerShell module project with an Invoke-Build backend for regular deployments and other automated tasks.
88

99
## Why use the ModuleBuild Module?
10-
<< Fill this out >>
10+
The answer is simple, it takes all the hard work out of authoring and maintaining your PowerShell module. To see why this is simply take a look at some of the features.
1111

1212
### Features
13-
<< Fill this out >>
13+
This build framework for PowerShell modules comes with several appealing baked in features which include;
14+
15+
- Fully portable project directory structure and build process. So portable that you can copy it to another PowerShell 5.0 capable system and it should run the same.
16+
- Automatically combine your public and private functions into one clean psm1 file at build time.
17+
- Automatically update your psd1 file with public functions at build time.
18+
- Automatically scan your module release with PSScriptAnalyzer
19+
- Automatically upload your script to the PowerShell Gallery (with appropriate API key)
20+
- Automatically create project documentation folder structure and yml definition file for ReadTheDocs.org integration
21+
- Automatically generate module documentation with PlatyPS
22+
- Visual Studio Code integration (tasks)
23+
- Easy to manage build configuration with forward compatible design and easy to use commands
24+
- Includes ability to scan for sensitive terms (like your company domain name or other items that you may not want published)
25+
- Helper functions to import existing project private and public functions into your ModuleBuild based project
1426

1527
## Installation
1628
ModuleBuild is available on the [PowerShell Gallery](https://www.powershellgallery.com/packages/ModuleBuild/).
@@ -24,10 +36,13 @@ To install:
2436
Install-Module -Name ModuleBuild -Scope CurrentUser
2537
```
2638

39+
## Examples
40+
I started this little framework as a build script for [one of my projects](https://github.com/zloeber/FormatPowershellCode) so you can see it in action there if you like (note that this is a very early version of the build script though). I've since taken that code, made it a bit more generic, and added an initialization routine for new projects. As an exercise I adapted [another older project](https://github.com/zloeber/NLogModule) to use this build script as well. So this framework does work for me but you might need to do some tweaking to get it working for your own project but keep in mind that any module that exports more than functions will take additional work. (See the notes below to better understand why.)
41+
2742
## Contributing
2843
[Notes on contributing to this project](Contributing.md)
2944

30-
## Change Logs
45+
## Change Log
3146
[Change notes for each release](ChangeLog.md)
3247

3348
## Acknowledgements

‎build/docs/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,4 @@
22
Any *.md file within the Additional folder will be automatically copied to the final doc folder at the root of the project directory.
33

44
## ReadTheDocs Manifest Creation
5-
See the README.md file within the ReadTheDocs folder for more information.
5+
Each folder in this path becomes its own subsection within the ReadTheDocs YML manifest file. This only covers the base folder and all the *.md files within it (so no subfolders will be recognized). Each public function you have in this module will automatically be included in this manifest file under a 'Function' section and do not need to be specified (as they will be automatically generated by PlatyPS).

0 commit comments

Comments
 (0)
0