Ruby Documentation - you can help update it!

todd burch · 3 Feb 2008, 03:08

Back in December, Google announced their Sketchup API blog:

SketchUp API Blog

Tips and Tricks for SketchUp Ruby API Developers.

(sketchupapi.blogspot.com)

A not-so-publicized aspect of it is that there is now a Ruby Doc WIKI over there too:

http://groups.google.com/group/SketchUp-Plugins-Dev

The biggest secret in town is that the doc at the above link is an updated version from the current Ruby Help.

An even BETTER aspect of all this is that I can edit all the doc to include more information, make clarifications, add better examples, fix incorrect information, and so on.

When you get to the Doc page, click on "view all". That brings up the whole list of classes. Then, you can click on "show page details" (upper right in the main panel) and then you can sort on the date to see what's been changed. For example, you can click on the Face class to see the updated doc for classify_point. The 'who updated it last' statistic is bogus, but the date is accurate.

With your help, we can really make this Ruby doc super. I've updated several of the html files already, as have some Google developers.

If you want a change to be made, document your change and post it here in the Ruby forum. Make the subject something identifiable, and prefix it with "[ruby doc]", like this: [ruby doc face.classify_point not documented]. If I don't see it after a reasonable amount of time has expired, send a PM to ping me. Then, I'll review your change and incorporate it into the doc. Sample code, fixed typos, more details - whatever you see fit. If I don't understand your update, we can discuss it here in the forum. We'll uses the posts here to track your changes. Please only request one topic change per thread so they don't get lost. For instance, if you have 5 changes for one method, post them in one thread. If you have updates for 5 different methods, post 5 different threads, one per method. Try to format your change to match the existing format.

If you just ask me to "update the transformation doc" or some such vague or extensive request, that ain't going to happen, and I will ask you to be more specific. As far as formatting, please don't bother to ask me to "change all the examples to have a blue background". I do stuff like this as I can, when I am editing for content, and as I have time.

So remember, make your requests for updates specific and thought out. I can help with the wording, and anybody else can participate in the wordsmithing too, if need be. If you have example code (even whole programs that don't stray too far from the method they describe) then post that too if you want it in the doc. Be sure it's tested and commented where need be. These things I'll be happy to incorporate.

Finally, before you request a change, to perhaps save yourself some effort, please check the above doc to make sure your change request has not already been made.

I hope this doesn't come across too "do it my way"-ish. The doc needs a lot of work, and it can't be fixed overnight. I'm just one guy, with a life, so I will get to changes as I can.

One comment I do want to make about the doc, and I've shared this directly with Google, is that the SU Ruby API doc, overall, is VERY good. I've been working with several other OO APIs lately, and they REALLY suck. @Last (now Google), organized the Ruby doc in an excellent manner and it should stand as an example for other development organizations to follow.

Todd

tomasz · 3 Feb 2008, 19:56

At Last!

Tomasz

Jim · 4 Feb 2008, 00:23

@unknownuser said:

Thanks for this Todd.

I will make this sticky for a while. (@Mods, please unstick after two months.)

Would it make sense to create a sub-forum for this?

todd burch · 4 Feb 2008, 00:34

If I had a vote, my vote would be to leave it here. One stop shopping for all your Ruby needs.

Jim · 4 Feb 2008, 11:12

@unknownuser said:

@jim said:

Would it make sense to create a sub-forum for this?

For just one post? Please clarify.

Todd has asked for this community to contribute SketchUp Ruby API documentation updates. My thought was that it would be easier for Todd to find and manage these document-related posts if they had their own sub-forum.

@unknownuser said:

On the topic of adding subforums, there is a common consensus - at least among the Moderators - to add as few new forums as possible. We actually prefer to shrink the index even further, but we've arrived at the point where we have ditched all the useless forums pretty much.
That said, once the transfer is complete (just 12 pages to go ladies and gents!) we will shortly introduce User Groups to the board. This is a feature that allows for people to 'subscribe' to whatever forums they want to see on the index. This way people can see as many or as few forums and subforums as they like. If someone wants to see less forums they can just unsubscribe to them, yet maintain full access to them, regardless of their subscription. (Needless to say, these subscriptions are free, as is always the case for everything in the entire SketchUp Community Forums.)

I understand.

todd burch · 19 Mar 2008, 19:53

In my opinion, everything is working fine. When I have seen discussions that warranted clarifications in the doc, I've updated the doc and mentioned the update in those threads.

What I had outlined above was a fairly formal process, and now I see it really doesn't need to be that formal. So far, the rate of changes hasn't even been close to overwhelming.

I guess now I would suggest that if a discussion occurs where it is mentioned the doc needs updating, and I don't see it and acknowledge that "I'm on it", then someone could PM me to alert me to the thread where the discussion is already taking place.

Todd

Jim · 31 May 2008, 18:16

I've created a bookmark-able search to make it easy to locate the [ruby doc] requests:

301 Moved Permanently

(www.sketchucation.com)

If I've missed any doc requests, let me know.

Direct · 26 Jun 2009, 15:58

Hello all,
I'm not sur it's the right place but ...
I would like to know if, instead of the default ruby console, it exist a user development interface like in C language, that let you program, debug inline (step by step etc.)
If exist such an "interactive" editor/interface it's really pretty hard to find where.
If it does not it really missing.

thomthom · 26 Jun 2009, 16:40

A quick forum search for "Debug" should give you a few results.

Direct · 27 Jun 2009, 15:56

@thomthom said:

A quick forum search for "Debug" should give you a few results.

Thanks

RobertCarlRice · 18 Oct 2009, 23:48

def ChangeCircleRadius( circle, center, radius )
	pts = Array.new
	curve = circle.first.curve
	curve.vertices.each do | vertex |
		vec = vertex.position - center
		vec.length = radius
		pts << center + vec
	end
	curve.move_vertices( pts )
end

Jim · 18 Oct 2009, 23:52

Robert - nice bit of code there.

I added the code tags around your ruby code. The code tags make the formatting a little nicer. Hope you won't mind.

Last but not least - welcome to the forum.

huckrorick · 6 Jan 2010, 15:49

This link leads to lots of dead end links.
http://groups.google.com/group/SketchUp-Plugins-Dev
Is this still functioning as you describe?

Huck

thomthom · 6 Jan 2010, 16:00

@huckrorick said:

This link leads to lots of dead end links.
http://groups.google.com/group/SketchUp-Plugins-Dev
Is this still functioning as you describe?

Huck

That's an old outdated link.

This is the current API reference: http://code.google.com/intl/nb/apis/sketchup/docs/index.html