When writing your scripts or modules have you not wished that it would all autodocument itself ? Isnt this what we should be aiming for when creating automations ? 🙂 So automations would automate documenting themselfes ?
This is exactly what automation should be about and today I’m going to show you how I create automated documentation for extremly big modules in seconds. As mentioned before we will be using MarkDown so it would be great if you would jump to here and get some more info if this is something new to you.
In order for this to work you must have a good habit of documenting your functions. This is the key to the success. Example of such a function documentation using comment based approach can look as following :
Creates magical events
This paramter defines how many people are looking at your screen in the time of invoking the cmdlet
This parameter defines how difficult it looks what you are currently doing
This function executes magical events all around you. By defining parameters you have direct control of how difficult it will seems this is and how many people are watching will have direct influence on range of events.
invoke-SomeMagic -NumberOfPeople 1 -DifficultyImpression 10
Creates really difficult looking magic for one person
invoke-SomeMagic -NumberOfPeople 100 -DifficultyImpression 10
Creates a magical show
# Function doing something here :) ...........
Auto documenting script
Now what an automation would be without automating it 😀 ? Below is my implementation of autodocumenting to MarkDown.
What I really like here is the fact that it will generate temporary file during documentation (I discovered encoding gives problems with online PDF converter ) . The whole can be changed to suit your needs and layout requirements.
Convert it to PDF
The last stage would be converting it to PDF. At the moment I’m using http://www.markdowntopdf.com/ to convert file prepared by above script. And I must say that results are extremly satisfying.
I have prepared small demo how it works in action. For this purposes I have created demo module with 3 dummy functions and then run the script. Below is snippet of how it looks. As mentioned before – I really like that and that kind of file can be nicely send to other engineer to quickly get the mfamiliar with your module.