You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/Usage/10 - Converting To ModuleBuild.md
+2-1Lines changed: 2 additions & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -25,8 +25,9 @@ So in order to convert an existing project to a modulebuild project you will fol
25
25
5. Add any required preload or postload code in src\other\preload.ps1 or src\other\postload.ps1
26
26
27
27
## Very Important Notes
28
+
28
29
- This will generally work well for easy projects. Modules with many dependencies or higher complexity levels will likely be more work to get converted.
29
30
- It is very important that, when specifying your module source, that you choose the right file. There are BIG differences in behavior between importing a psm1 file and a psd1 file and whichever one you pass in will be the one that gets imported.
30
31
- I'd only run these commands against a newly initialized project but you could theoretically use this to split up some monolithic module for development purposes. Conversely, you could also use these to merge the public/private functions of multiple disperate modules as well.
31
32
- These helper functions are also to be used for migrating existing modulebuild projects to updated versions of modulebuild in the future. All you have to copy over from an existing modulebuild project after importing the private/public functions is the json configuration file, your preload/postload customizations, and additional paths.
32
-
- If you tend to use your module project directories as dumping grounds for ideas and scratch code you may want to clean things up a bit before importing your private functions. Otherwise you could be in for a long process of yes/no prompts.
33
+
- If you tend to use your module project directories as dumping grounds for ideas and scratch code you may want to clean things up a bit before importing your private functions. Otherwise you could be in for a long process of yes/no prompts.
Copy file name to clipboardExpand all lines: docs/Usage/3 - Build A Release.md
+3-1Lines changed: 3 additions & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -13,6 +13,7 @@ or in VS Code
13
13
Press 'Ctrl+Shift+B' then select 'Build'
14
14
15
15
This is the heart of the ModuleBuild project. The build will go through the process of combining the source files into a monolithic psm1 file, populating the exportable functions of the release module manifest, creating online help files, analyze the script, scan for sensitive terms, and more. If everything builds without errors you will see the results populated in the release directory in two areas:
16
+
16
17
1. In the release directory in a folder with the same name as the module (which is best practice for a module)
17
18
2. In the release directory in a folder with the version number of the release.
18
19
@@ -23,4 +24,5 @@ At this point you should have a working release you could theoretically have som
23
24
**Note:***The build will pause if you didn't have enough comment based help to create the help file. Now is a chance to look at the created markdown files it references in the temp\docs directory to see what is missing. Use this as a chance to round back on your CBH in the source function files and update it to fill in the gaps. Then restart the build process again. Alternately, you can update the markdown files directly then continue the build process but this is NOT recommended as it is a temporary solution at best.*
24
25
25
26
## Pre and Post Build Steps
26
-
If you have some things you need to do before or after your build simply drop ps1 scripts in to build\startup or build\cleanup (respectively) to have them run. This project uses build\startup\makeplastermanifest.ps1 to go through the custom plaster manifest build process for instance.
27
+
28
+
If you have some things you need to do before or after your build simply drop ps1 scripts in to build\startup or build\cleanup (respectively) to have them run. This project uses build\startup\MakePlasterManifest.ps1 to go through the custom plaster manifest build process for instance.
Copy file name to clipboardExpand all lines: docs/Usage/4 - Test A Release.md
+2-1Lines changed: 2 additions & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -1,4 +1,5 @@
1
1
# Step 4 - Test a Release
2
+
2
3
You may get a build to complete without errors but that doesn't mean that the module will behave as expected. You can do a quick module install and load test if you like:
3
4
4
5
`.\Build.ps1 -InstallAndTestModule`
@@ -18,4 +19,4 @@ or
18
19
19
20
or in VS Code
20
21
21
-
`Ctrl+Shift+B (then select "Build, Install, and Test Module")`
22
+
`Ctrl+Shift+B (then select "Build, Install, and Load Module")`
# Step 5 - Upload A PowerShell Gallery Release (Optional)
2
-
If you have plans to upload your module to the PowerShell Gallery then this build script can help automate the process a bit. You will still need to create an account and attain an API key from the PowerShell Gallery [website](https://www.powershellgallery.com/).
3
-
4
-
Once you have attained your API key you will need to update your build configuration file with it. From witin your project root directory do the following:
Now when you are ready to upload to the psgallery simply run the following:
9
-
10
-
`.\Build.ps1 -UploadPSGallery`
11
2
12
-
Assuming you have a valid NugetAPI key defined and your PowerShell manifest file has everything the gallary requires then this build step will automatically update the the upload the recent release directory module to the PowerShell Gallery for you.
3
+
If you have plans to upload your module to the PowerShell Gallery then this build script can help automate the process a bit. You will still need to create an account and attain an API key from the PowerShell Gallery [website](https://www.powershellgallery.com/).
13
4
14
-
**Note:***I've not figured out yet how to reset versions when uploading to the gallery. You always have to upload a newer version than what is already there so be extra certain you are ready to publish the module before doing this step.*
5
+
Once you have attained your API key you will need to update your build configuration file with it. From witin your project root directory open the following file:
6
+
`build\YourModuleName.buildenvironment.json`
15
7
16
-
Hey, one more point, you can chain things together and do a build, install and test, and upload to the powershell gallery in one fell swoop:
Now when you are ready to upload to the PSGallery simply run the following:
23
21
24
-
or in VS Code
22
+
`.\Build.ps1 -UploadPSGallery`
25
23
26
-
`Ctrl+Shift+B (then select "Build, Install, Test, and Publish Module")`
24
+
Assuming you have a valid NugetAPI key defined and your PowerShell manifest file has everything the PSGallary requires then this build step will automatically update the the upload the recent release directory module to the PowerShell Gallery for you.
27
25
28
-
After this has completed the build version number will automatically be incremented by 1 and updated in your build configuration and the main module manifest file.
26
+
**Note:***I've not figured out yet how to reset versions when uploading to the gallery. You always have to upload a newer version than what is already there so be extra certain you are ready to publish the module before doing this step.*
**Note:** It should be noted that performing the InstallAndTestModule build step is a bit superfluous as that gets done prior to uploading to the PSGallery as well. Also, you usually will be working on a release/build a bit before going straight to releasing to the gallery so I generally don't recommend doing everything in one fell swoop like this. You also get a much cleaner build experience if you simply use the invoke-build command to string the build steps together.
Copy file name to clipboardExpand all lines: docs/Usage/7 - Project Documentation.md
+9-3Lines changed: 9 additions & 3 deletions
Original file line number
Diff line number
Diff line change
@@ -1,4 +1,5 @@
1
1
# Maintaining Project Documentation
2
+
2
3
Keeping documentation updated for your project comes in two forms with the module code scaffolding that this project creates.
3
4
4
5
1. You keep your comment based help for public functions updated. PlatyPS will use this to generate function documentation.
@@ -13,13 +14,14 @@ Your module documentation also comes in a few different forms and locations that
13
14
>**NOTE:** If you get one thing from this section it is that you should **NOT** be updating your project documentation in the .\docs folder directly. Instead, use the build\docs folder to update your documentation and it will automatically populate to your project .\docs directory at build time.
14
15
15
16
## Comment Based Help (aka. CBH)
17
+
16
18
This build project assumes that the comment based help in your public functions are the single source of truth for your documentation.
17
19
18
20
ModuleBuild uses PlatyPS to generate the relevant help files at every build. The build will fail if "{{ blah blah blah }}" is found within the PlatyPS markdown output. PlatyPS puts this marker text in place when you have missed parameters, synopsis, descriptions, or other essential CBH sections.
19
21
20
22
It is possible to setup the build process in a manner that would allow us to manually make updates to the .md files and then continue processing. But I've purposefully decided against this so you are encouraged to go back to your original functions, fix/change the offending CBH, and rebuild.
21
23
22
-
Once PlatyPS autodocumentation is complete the CBH for each function gets replaced with the generated module documentation link. I base this replacement code on '.SYNOPSIS' existing in the comment based help. This is done in the following task:
24
+
Once PlatyPS auto-documentation is complete the CBH for each function gets replaced with the generated module documentation link. I base this replacement code on '.SYNOPSIS' existing in the comment based help. This is done in the following task:
23
25
24
26
```powershell
25
27
task UpdateCBH -Before CreateModulePSM1 {
@@ -38,21 +40,25 @@ As you might expect this will remove the entire CBH block which may or may not b
38
40
>**NOTE:** ModuleBuild recreates the documentation markdown files every time the documentation gets generated. This includes the module landing page. PlatyPS doesn't seem to automatically pull in function description information (or I'm missing something in the usage of this module) so I do so within another task behind the scenes.
39
41
40
42
## CBH Helper
41
-
I've included a special task called 'UpdateCBHToScratch' that will recurse through your public functions and look for those that don't have CBH and add it. These files get spit out to your scratch directory and can be inspected for possible reintegration into your project. You can run this process at anytime with the following switch:
42
43
43
-
`.\Build.ps1 -InsertCBH`
44
+
I've included a special task called 'AddMissingCBH' that will search through your public functions and look for those that don't have CBH and add it. These files get spit out to your scratch directory and can be inspected for possible reintegration into your project. You can run this process at anytime with the following switch:
45
+
46
+
`.\Build.ps1 -AddMissingCBH`
44
47
45
48
If you have a large project with little CBH this can be a good way to kickstart the process so the build process will start working. Additionally, if you add a bunch of public functions without CBH you can use this process to fill things out temporarily until you have time to round back and add better details.
46
49
47
50
>**NOTE:** This process requires you to copy the resulting files back into your project to be of any use.
48
51
49
52
## Generic Documentation
53
+
50
54
Most of your documentation will come from two sources, the auto-generated function markdown that PlatyPS spits out and the build\docs\Additional folder.
51
55
52
56
## ReadTheDocs.org Integration
57
+
53
58
If you have enabled readthedocs.org integration in the ModuleBuild configuration then a mkdocs.yml file will get updated automatically at the root of your project directory. It is up to you to setup the integration between your github.com account and readthedocs.org for this to be of any use in your project. When setting up your project at the ReadTheDocs website remember to set the advanced settings for 'mkdocs' processing.
54
59
55
60
### ReadTheDocs YAML Configuration
61
+
56
62
The ReadTheDocs manifest file gets generated from three locations:
57
63
58
64
1. The folder structure in .\build\docs\ReadTheDocs - Each subfolder becomes a category with each markdown document within becoming a specific page within it.
0 commit comments