PowerShell HelpWriter 2017: What’s New? (Part 2)

We’ve written a series of blog posts to introduce you to the newest features of the product and in this release, we made major changes to PowerShell HelpWriter.

In Part 1, we looked at the new UI changes to the designer and the editor.

In Part 2, we are looking at the new project feature for PowerShell HelpWriter.

 

Projects

PowerShell HelpWriter introduces projects to manage multi-file help, deployment and to keep track of the source module.

 

Are projects required?

No, you do not have to use projects to maintain your help files, but using a project will have the following benefits:

  1. Keep track of the source module, which allow you to rebuild the help files in order to reflect changes in the module.
  2. Organize all your help files in one location without having to leave PowerShell HelpWriter 2017.
  3. Automatically backup existing help files when a module version changes or when you rebuild the help.
  4. Ensure that you have access to project specific features and upcoming project features.

 

How do I create a project?

PowerShell HelpWriter 2017 will create a project when you select the Help Project (From Module) command or the New Help Project (Empty) commands.

New Help Project

 

If you select Help Project (From Module), you will be presented with a dialog to select the module from which to generate a help file.

Select Module Dialog

Optionally, you can use the Browse button to select the module. You will need to use this option if the module is not located in a discoverable PSModulePath directory.

 

Next you are presented with the New Help Project dialog. This dialog will allow you to configure the project’s settings and name.

New Help Project Dialog

Setting Description
Project Name Sets the name of the project. This defaults to the module’s name.
Location The folder to save the project in.  You will want to keep the help project outside of the module folder otherwise the project files and backups may clutter your module directory.  The default location for projects is:

\My Documents\SAPIEN\Help Projects

Create Project Folder Creates a subdirectory in the Location folder using the project’s name.
Language Folder Sets the destination folder within the project to store the help files. The default value is dependent on the default culture of the computer.

For example: en-US for English (United States).

Rebuild Using Specifies what method HelpWriter should use to import the module in order to rebuild the help files.

Module’s Path:
Rebuilds the help files by using the module’s file path to import the module.
Use this setting when you want a specific version of the module or when the module is located outside a PSModulePath directory.

Module’s Name:
Rebuilds the help files by using the module’s name to import the module.
Use this setting when you want rebuild using the latest version of the module as determined by PowerShell.
Note: The module must be located in a PSModulePath directory.

Once you have selected your options, press the Create button and you now have your new project.  The newly created project will contain a sample about topic for your convenience. Now you can use the Project panel to modify the project settings or edit the generated files.

 

Project Panel

The Project panel allows you to add, remove and manipulate the project files. You can also use the panel to open the project’s folder or the module’s folder in Windows Explorer. Those of you who work with projects in PowerShell Studio, will find this panel familiar.

Project Panel

The project contains the specified language folder and a sample about text file, in addition to the generated help files.

From the Project panel, you can:

  1. Rename files or the project.
  2. Add new files to the project.
  3. Add existing files to the project.
  4. Create folders
  5. Open the project folder in Windows Explorer.
  6. Open the module’s folder in Windows Explorer.
  7. Refresh the module information (see below).
  8. Deploy the help files to the module (see below).
  9. Rebuild the help files from the module (see below).

Select a file node or the project node in order to modify the settings in the Properties panel.

 

Properties Panel and Project Properties

As, we mentioned the Properties panel allows you to modify file or project properties/settings depending on the selection in the Project panel.

Properties Panel

 

Now we will take a look at the project’s properties.  The project’s properties are grouped into two categories: Module and Project.

Project Category

The project category pertains to the project itself.

Property Description
Project Name Specifies the name of the project. You can rename the project by editing this property.
Project Path Displays the location of the help project.

 

Module Category

The module category contains the module specific information and settings.

Property Description
Module Name Specifies the name of the Module. This value is used to rebuild the help file depending on the Rebuild Using property (see below). You can edit this value.
Module Path Displays the location of the help projects. This value is used to rebuild the help file depending on the Rebuild Using property (see below). You can edit this value to select a specific version of the module.
Module Version The last detected version number of the module.
Rebuild Using This property was determined in the New Help Project dialog (See above).
Rebuild Using specifies what method PowerShell HelpWriter will use to import the module in order to rebuild the help files.

Path:
Rebuilds the help files by using the project’s Module Path property to import the module.

Name:
Rebuilds the help files by using the project’s Module Name property to import the module.

 

Deploying Help Files

Since the project is purposely kept outside the module’s directory, we added the Deploy command.

Ribbon - Deploy

Use the Deploy command to ensure your help files are accessible by PowerShell when loading the target module. When you deploy, PowerShell HelpWriter will copy the project’s help files, including the folder structure, over to the module’s directory. The module location is determined by the project’s Module Path property.

Deploying

 

Important: If you generated xml help from comment-based help, you will need to update any exported function’s help-comment to include a .EXTERNALHELP line:

<#
.EXTERNALHELP MyModule.psm1-Help.xml
#>
function Get-MyFunction
{

}

 

Rebuilding Help

The Rebuild command will reconstruct the help files from the source module and will replace the existing files in the project.

Ribbon - Rebuild

Automatic Backup

Before rebuilding and replacing the help file, PowerShell HelpWriter automatically backup all your project files to the following directory:

Project Folder\Help_Backup\version number\

For example:

MyHelpProject\Help_Backup\1.0.0.0

The version number is determined by the project’s Module Version property. If the Rebuild command fails, the application will automatically restore the files.

If you wish to roll back the rebuild changes, you can copy and replace the files using the backup copies.

 

When you run the Rebuild command, you will be presented with the following dialog, which asks what action you would like to take:

Rebuild Action

You can select the following actions:

Action Description
Deploy to and rebuild help from the module This action will deploy the file helps to the current module location before rebuilding the help files. This ensures the help content is present in the newly constructed files.

Important: If you are using the Rebuild By Name setting, PowerShell may rebuild the help from another location, which can mean the newly deployed help files may not be present. Therefore, it is recommended to check the module beforehand by using the Refresh Module Information command (see below).

Rebuild help from the module This action will simply rebuild the module help files without deploying the project files.

Target Language Folder

Use the Target Language Folder setting to build the help files in a specific language folder.
Note: PowerShell HelpWriter will default to the first language folder in the project. If not found, it will use the culture setting of the OS.

After making your choice and pressing the OK button, PowerShell HelpWriter will start the rebuilding process and display a progress dialog:

Rebuilding Help Progress

You can press the Cancel button to stop the process and to restore the original files from the backup.

Upon a successful completion, PowerShell HelpWriter will list the files that were added and/or updated:

Rebuild Output

 

Refreshing Module Information

The Refresh Module Information commands triggers PowerShell HelpWriter to query the module information using the method determined by the project’s Rebuild Using property.

It is recommended to use this command before using the Rebuild command, especially when using the Rebuild Using Name setting.

Ribbon - Refresh Module Info

If PowerShell HelpWriter detects a change in the module, such as the version, location or name, it will present you with the following dialog:

Module Info Changed

The dialog displays the found module and the stored information determined by the project properties. It also presents you with the follow actions to perform:

Action Description
Deploy to and rebuild help using the new version The action deploys the help to the new module location / version and then rebuilds and replaces the help files in the project.
Rebuild help using the new version The action rebuilds the help files without deploying the project files.
Update module information only It will update the project’s settings without rebuilding or deploying.

When you press the OK button, PowerShell HelpWriter will automatically backup the help file using the current module version before updating the module information.

If you selected a rebuild action, it will then run the Rebuild command as discussed above.

 

As you can see, projects contain many useful features such as, file management, automatic backups and deployment capacities. These features allow you to work outside of the module and to respond to new versions of the module.

 

Please continue providing your feedback. Many of the new features included in the service builds are suggestions from users like you. Therefore, if you have any suggestions or feature requests, please share them with us on our Wish List and Feature Requests forum.