Skip to content

Latest commit

 

History

History
77 lines (54 loc) · 5.6 KB

README.md

File metadata and controls

77 lines (54 loc) · 5.6 KB
Raw

Documentation

Most documentation is generated from the comment-based help in the module functions. This means that the documentation is always up-to-date with the code. You don't need to format the comment based help correctly as any issues should be discovered when your PR is merged to the prerelease branch but if you need to make changes to the documentation locally you can follow the steps below.

Testing the Documentation Locally

This requires you have nodejs v20 installed. If you don't have nodejs installed, you can install it from nodejs.org or you can use my preferred method of using nvm-windows.

  1. Clone this repository and open a terminal in the root directory.
  2. Install the HelpOut PowerShell module by running Install-Module helpout -Scope CurrentUser -RequiredVersion 0.5. Version 0.5 is required because changes to the formatting in HelpOut can break the Markdown generation and 0.5 is what's being used in the Github Actions.
  3. Change to the docs directory cd .\PwshSpectreConsole.Docs.
  4. Run npm install.
  5. Run npm run dev to start the dev server. You should be able to view the documentation at http://localhost:4321
  6. To update the help for the public functions:
    • Press ctrl-c in the terminal session that's hosting the docs dev server to stop it.
    • Update the comment based help in your public functions. See Comment Based Help below for more information on how to format the help docs.
    • Run npm run update-docs:no-commit -- -TargetFunction Set-SpectreColors again to see the changes for the function you've changed, replace "Set-SpectreColors" with the function you're working on. The dev server will start again after updating the docs and you can view the changes at http://localhost:4321.
  7. When you're happy that the docs look correct you can open a PR with the changes. You don't have to commit the docs files, they will be autogenerated when your branch is merged into the prerelease branch of PwshSpectreConsole.

Note

If you're having troubles running the docs update because it can't delete files, it's likely that the files are locked by the PowerShell session in your editor session. Try closing your editor and running the update again.

Comment Based Help

The comment based help in the module functions is used to generate the markdown for the documentation site. The comment based help is written in a specific format to ensure that the markdown is generated correctly.

When generation the help the following fields are used and others are dropped:

  • DESCRIPTION is used as the main description on the docs site.
  • PARAMETER documentation will be kept and grouped under Parameters on the docs page.
  • EXAMPLE documentation is the hard part so two examples are provided below. You can provide multiple examples.

Warning

You can't start your example with a comment line. There is a limitation in the way that the markdown is generated that means the first line of the example can't be a comment or it will break the markdown generation.

Example 1 - Basic Example

For a standard function a simple example will only require the code required to make the function do its magic. In the example below the function Format-SpectreBarChart is used to create a bar chart but it requires data setup. The example code needs to work as one full statement that you could copy and paste into a PowerShell console so the data setup is part of the example.

<#
    .EXAMPLE
    $data = @()

    $data += New-SpectreChartItem -Label "Apples" -Value 10 -Color "Green"
    $data += New-SpectreChartItem -Label "Oranges" -Value 5 -Color "DarkOrange"
    $data += New-SpectreChartItem -Label "Bananas" -Value 2.2 -Color "#FFFF00"
    
    Format-SpectreBarChart -Data $data -Label "Fruit Sales" -Width 50
#>

See the example in action at: https://pwshspectreconsole.com/reference/formatting/format-spectrebarchart/

Example 2 - Advanced Example

For more complex functions you may not be able to generate an example without providing user input. If you were to try and generate an example for a function like was required for Read-SpectreText you would need to simulate a user typing.

To generate user input you can add a # Type comment at the point in the example where the input is required. The example generator takes each double quoted string after the directive as a separate piece of user input, multiple inputs can be provided by separating them with a comma.

e.g.

  1. # Type "This is a test" will type the string "This is a test" into the console with some delay between each character.
  2. # Type "This is a test", "↲" will type the string "This is a test" and then press enter afterwards.
  3. # Type "a" will enter a single character "a" into the console.
  4. # Type "↑", "↓", "↲", "<space>" will press the up arrow key, down arrow key, enter, and space keys respectively.
<#
    .EXAMPLE
    $favouriteColor = Read-SpectreText -Question "What's your favorite color?" -AnswerColor "Cyan1" -Choices "Black", "Green", "Magenta", "I'll never tell!"
    # Type "orange", "↲", "magenta", "↲" to enter text that must match a choice in the choices list, orange will be rejected, magenta will be accepted
    Write-SpectreHost "Your favourite color is '$favouriteColor'"
#>

See the example in action at: https://pwshspectreconsole.com/reference/prompts/read-spectretext/