Skip to content

Comments

Workflows to generate and publish documentation and online help#199

Merged
jakehildreth merged 20 commits intojakehildreth:testingfrom
SamErde:se-mkdocs-01
Dec 26, 2024
Merged

Workflows to generate and publish documentation and online help#199
jakehildreth merged 20 commits intojakehildreth:testingfrom
SamErde:se-mkdocs-01

Conversation

@SamErde
Copy link
Collaborator

@SamErde SamErde commented Dec 21, 2024

This pull request introduces several new workflows, scripts, and documentation updates to improve the automation and documentation processes for the Locksmith module. The most important changes include adding workflows for creating external help and deploying MkDocs, updating documentation configurations, and adding scripts for generating and repairing documentation.

New Workflows:

  • Create External Help Workflow: Adds a GitHub Actions workflow to create and package external PowerShell help using PlatyPS. This workflow runs on Windows and includes steps for checking out the repository, displaying the path and PowerShell version, and creating the help package. (.github/workflows/Create External Help.yml)
  • Deploy MkDocs Workflow: Adds a GitHub Actions workflow to deploy MkDocs documentation to GitHub Pages. This workflow runs on Ubuntu and includes steps for checking out the repository, setting up Python, installing dependencies, building and deploying MkDocs, and updating the index and README files. (.github/workflows/Deploy MkDocs.yml)

Documentation Configuration:

  • Read the Docs Configuration: Adds a configuration file for Read the Docs to specify the build environment, Python version, MkDocs configuration, and requirements file. (.readthedocs.yaml)

New Scripts:

  • Markdown Repair Script: Adds a PowerShell script to repair markdown files generated by PlatyPS, specifically addressing issues introduced in PowerShell 7.4. (Build/MarkdownRepair.ps1)
  • HelpOut Documentation Script: Adds a PowerShell script to generate module documentation using the HelpOut module, including creating markdown and MAML help files and an external help cab file. (Build/Write-HelpOutDocs.ps1)
  • PlatyPS Documentation Script: Adds a PowerShell script to generate documentation for the module using PlatyPS, including creating markdown files for each function, a general module page, and an external XML help file. (Build/Write-PlatyPSDocs.ps1)

Documentation Updates:

  • Invoke-Locksmith Documentation: Adds detailed documentation for the Invoke-Locksmith cmdlet, including its synopsis, syntax, description, examples, parameters, inputs, outputs, notes, and related links. (Docs/Invoke-Locksmith.md)

@SamErde SamErde self-assigned this Dec 21, 2024
@SamErde SamErde added documentation Improvements or additions to documentation enhancement New feature or request labels Dec 21, 2024
@jakehildreth jakehildreth self-requested a review December 26, 2024 13:54
Copy link
Owner

@jakehildreth jakehildreth left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I understand this PR this much:

  1. It is not malicious.
  2. It does what Sam has described it to do.
  3. It makes Sam the official CI/CD guy for Locksmith.

@jakehildreth jakehildreth merged commit e6d41ec into jakehildreth:testing Dec 26, 2024
@SamErde SamErde deleted the se-mkdocs-01 branch December 26, 2024 22:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants