How to generate beautiful PowerShell documentation
I’m currently maintaining a suite of powershell modules called poshBAR, and there’s a lot of activity going on in the library right now. The last thing I want to do is write all of the documentation for this library, and then try to remember to edit it when the API changes.
So with this, I began searching around to see if anyone has already created a documentation generator… and yes, there are a few out there. The trouble I had was two fold
- It needed to be beautiful to look at.
- It needed to be simple to invoke, with sensible command parameters.
With those two in mind, there was one script that I found that did a pretty good job overall. The example I found was located over at poshcode. It’s pretty rough around the edges, but gave me a little kickstart to get what I needed.
With a little help from Matt on a StackOverflow Question that I had, I went on to heavily refactor pretty much all of the original example. I split it into two files, a template, and the runner, and I brought in a little Bootstrappyness for beautification. Essentially, all you need to do is import your module, and kick off the script.
Import-Module MySpecialModule .\psDoc.ps1 -moduleName MySpecialModule
If you’d like to look at (or improve) the repository, it can be found on github under psDoc.
If you’ve got bootstrap chops, I’d be happy to get a little help, it’s one area I’m not great it, and I know it could use a little improvement.
Edited to remove the old gist and instead point to the psDoc repository.