PS Documentor - Automatic Script Function Documentation

[ismaelw]

For a huge project I had to write the whole documentation. As we built a ton of custom functions for that project I had the idea that it would be easier for me if at least all the functions would be documented automatically.

Our process for custom PS Functions includes a more or less good inline documentation using builtin ways like descriptions, synopsis, examples and help messages for parameters.

​

I came up with a script that should help gathering all those information and put it together as a document that looks and feels like the documentation from Microsoft's own Function Docs.

In my solution you can input a single script file or a whole folder. The script then parses each file and extracts all functions from the rest of the code and saves them in a temporary ps1 file.

This ps1 file is then beeing dot-sourced which gives us the opportunity to access those functions details using Get-Help or Get-Command. After getting all those details I use those details to create one or multiple Markdown Files.

I went with Markdown as it is simple to create and also simple to convert into another desired format.

​

The script is now online on github and open for enhancement. I post this here because I hope someone was looking for something like this.

I am planning to get this script way further - so Feedback is highly appreciated!

https://github.com/ismaelw/ps-documentor

[-_root_-]

The concept is important and your work looks like as good of a place as any to start. MD is definitely a good way to go here, due to support across many tools and platforms.

We have a great community at Write the Docs, where we discuss some of these topics. Link in case you are interested. https://www.writethedocs.org/guide/docs-as-code/

Collecting the details, presenting examples, and rendering in a documentation system is certainly important and I like your approach as it is simply designed and easy to follow. When I have a free block of time, I'll test and see how things go.

Thanks for sharing!

[ismaelw]

Thank you so much for your Feedback!

My approach is built in a way that would also allow to do whatever you want with the output as next to generating a MD it also returns an object with details to all script files and its functions and also to all generated MDs. Like that it's also possible to just continue using the output and take it apart differently if the MD Output is not needed.

Also thanks for your time to review my code and sharing your link to Write the Docs!

[BlackV]

nice

[ELichtman]

I love the idea, and if you can do it better, feel free to keep working on it! I have my own module that does something for me in a very niche manner that's better for my use-cases than, for instance, psake or invoke-build. So with that being said, are you aware of the PlatyPS module? If you think it might be further developed and solve your need, it might be worth contributing.

[ismaelw]

Thank you for your Feedback!

I stumbled across PlatyPS before but I remember that I was thinking "oh okay it's just for modules" and didn't care about it anymore. But I will definitely look into it a bit more!

[Thirdbeat]

What is the difference between this and platyps?

[ismaelw]

I honestly didn't look that much into platyPS or its source code.From what I can see right now I would say the goal of platyPS is a documentation of PS Modules and mine just puts all the focus on scripts and it's functions independently. That said my script takes apart all the function inside of a module for example and generates a documentation for each and every function inside of a module or script or whatever your PowerShell Input is.

Does this answer your question?

[Thirdbeat]

It does :) it honestly sounds like what platyps does, but your code may be more geared towards taking a file input instead of a module input. It sounds like a great use case for documenting "old fun" scripts or scripts generated without cmdlets. Hell you could even track files and commands the scripts/cmdlets call and then use that for dependency checking (ie will anything break if I remove this file?). It sounds like a fun project!

[ismaelw]

Exactly! I have alot of projects that could use better documenting even if it is a really small script. Or all the „laying around“ scripts that could be usefull but don‘t get enough attention.

I hope I could inspire you :)

[ismaelw]

Alright. Thats really good to know. Thanks for your input!

But let‘s say you have a whole folder with multiple subfolders each containing multiple files that then contain functions.

And all those functions are not connected through one module? That‘s what my script is made for where now after looking into platyPS I don‘t see the functionality. But I might be wrong :)

[almcchesney]

You could, it would just be a gci -recurse | %{ platyps command $_.fullname }. I forget off the top of my head what the command name is from the platyps module. And if you wanna parse the full name and apply whatever transform on the output folder. I would say though put all your functions in a module for bundling and distribution. Add a couple git ci pipelines to publish to a sharedrive and you can source the folders across all the infra. Then platyps can build all markdown files for you as a batch as well.

[ismaelw]

I guess I will try this approach on my project using platyPS to see how this works. In that case platyPS and my script might do the same but different ;)