Auto Generating Automate Guide


#1

This is quite a hot topic,

The well known “Methods available to Automate” is also known as the Automate Bible.

We have such tools as XMLinspect, and InspectME and even Object Walker to try and make sense of the workspace, whats in it and whats available.

It seems to me that the bible would be suited to auto generate itself from the code? As the only one who really knows what methods are available, and what parameters are required to drive methods is the code base itself.

This topic is particularly around the Automate Bible, as it lends itself to this construction where as the other guides are true user guides, not references and therefore need more personal care and loving to them.

To the developers in ManageIQ, do you think this is something that we should look to do for this guide, currently its always trying to stay current, and with automate being one of the fastest growing areas of the platform that can be difficult.

Now, not meaning to name drop here, but .NET IDE does a very good job of collecting comments in code into documentation bundles. Is this something Ruby has adopted too?

@tinaafitz, @mkanoor, any thoughts on the automate guide?

Thanks


#2

@jhardy This sounds like documenting the ruby code that makes up automate.

Would something like rdoc/yard be something to try?

http://mikeperham.com/2010/12/16/using-rdoc/

It generates documentation similar to this: http://api.rubyonrails.org/


#3

@jhardy, @matthewd pointed me to http://yardoc.org/ particularly, the [Getting Started guide] (http://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md)


#4

@jhardy I think it’s a fantastic idea!

Attempting to keep the automate bible up to date is especially challenging and time consuming.

I’m going to check out the information that @jrafanie provided.


#5

I’d be all for yard documentation there.