As a beginner, I feel like I’m missing out on some advanced testing workflows, and was wondering if there were any tutorials or guides explaining different workflows or tools available for creating Ruby scripts/extensions for SketchUp?
For example, beginners (I may or may not be speaking from personal experience, lol) might go through this progression:
Inside SketchUp, opening the Ruby console and typing in one-off lines of code and executing it. Wow! cool. I want to do more!
Upgrading to Ruby Console+ and writing multiple lines of code to execute.
Copying + pasting code from an external editor (better interface, github) into the console to test it.
Writing one huge script in an external editor (not knowing how to properly split things up into multiple files.)
Making the leap from one script, to a “proper” extension with multiple files, and trying to learn how to effectively load it into SketchUp and test it without having to restart SketchUp each time, lol.
I’ve come across various tools like autocomplete for various code editors, things like TestUp@thomthom , and maybe some other things that can load your extensions on the fly. And they all seem very useful, it’s just when I read the documentation it’s all over my head. Is there a beginner-friendly guide going through the various stages of developer workflow, from beginner one-liners, all the way to properly organized extension? Complete with testing and debugging tools and how to configure them? Like, how do the pros set things up when creating a new extension? Are there templates they use?
There seems to be a gap between general Ruby standards/knowledge and SketchUp Ruby API-specific knowledge, and I sometimes get lost in between. Aside from this valuable subforum, there really aren’t many people teaching how to do this stuff.
It’s like most of the documentation is targeted towards Ruby developers who want to learn the SketchUp API, rather than SketchUp enthusiasts who want to learn Ruby in order to leverage the SketchUp API.
It would be great to get feedback on where you find yourself stomped. For us writing this it’s easy to become blind to the challenges of getting into a new topic. We have a lot of resources on our GitHub repository, the first thing I’d recommend is setting up a GitHub account and use the Issue Trackers in the various repos. We’d love to work with you in improving the guides and tools.
One attempt is this repository:
You’ll see that it have two main folders, examples and tutorials. The tutorials are heavily commented, explaining every single line. At the moment there are two, one showing the absolute minimum for an extension (with the file structure needed for Extension Warehouse) and the other introduces Ruby tools.
The Examples folder has more, but is not as heavily commented. It’s more aimed at showing various common concepts.
We have this VSCode github template, GitHub - SketchUp/sketchup-extension-vscode-project: VSCode Project for SketchUp Extension Development. You can choose to Use This Template to create a new repository, in which you will have complete base setup for writing SketchUp extensions using VSCode with code insight and debugger configurated. However, it’s not 100% plug-and-play if you’ve never used it before, it does require having Ruby installed on your machine. There is a lot of room for improvements to the README etc. Log an issue in the tracker and we’ll try to fill in the blanks.
Yes, in large part we do assume existing Ruby/programming experience. Teaching the basics of programming in a challenge of its own. For those who have never touched programming I tend to recommend they start with the official learning resources of that language. Ruby has it’s own “Getting Started” section where you can play around in the browser. Also a “Ruby in Twenty Minutes”.
During the first virtual dev meetup yesterday it was suggested that we cover topics such as the debugger, TestUp etc. It’s something we’ve done at DevCamps before, and doing so to a wider audience would be nice. It also got me wondering if it might be any interest in us doing videos/screencasts of our setups?
Personally I use VSCode a lot, but I also have RubyMine. Both have their strengths. For my extension projects I either use that VSCode github template or my custom tool skippy (GitHub - thomthom/skippy: CLI Development tool for SketchUp extensions) to quick-start the boiler-plate.
TestUp is also a key tool in delivering stable products. I got to admit that I haven’t leveraged it much for my small free extensions. But certainly in my commercial ones they are critical to avoid regressions.
Another advanced tool, that I don’t have the need for in most of my extensions, but when performance becomes critical it’s alpha and omega to be able to profile your code and really understand where the bottlenecks are. (GitHub - SketchUp/speedup: Profiling tool for SketchUp Ruby extensions.)
All of this I’d love to make more accessible. Lowering the bar for more people to get started with extensions, and providing paths to rapidly deliver extensions of high quality.
If you would care to provide us with feedback on where you are stuck we’ll work with you. Best thing is to file specific issues in the various projects’s github repos. Makes it a lot easier for us to respond faster with concrete solutions/improvements.
If it’s about general concepts where you’ve not found relevant tool/example on github, start a thread here and we’ll talk.
The SketchUp API documentation is a concise dictionary of the API’s modules, classes and their methods. It is not a teaching tool and the snippets that are shown are mostly taken out of context and often not that helpful.
Contrast this with the SketchUp C API which have no snippets at all.
Trimble and it’s SketchUp division are not really in the programming education business. It is not their responsibility to teach basic programming concepts. The web has free and paid tutorials on this available. Or a person can take a night course at their local junior college.
The same holds for Ruby. The SketchUp API simply extends core Ruby and a coder needs to learn Ruby first. If they don’t, then the SketchUp API documentation looks to them like a foreign language.
This should be done somewhere after your step 2 and before step 4. I know that enthusiasts usually don’t formally attempt to learn Ruby during 1 or 2.
There are many free resources to learn Ruby and Trimble need not reinvent the wheel here:
Agree, and @Matt I’m not knocking the gist of what you said above. I remember how the learning curve was very steep back in the day (what? 12 years ago now?) … and I had a background and formal college coursework in programming myself.
Yeah, I understand that. It’s also not their responsibility to teach people how to use SketchUp to model different types of projects, but Aaron produces several YouTube videos doing just that.
I just feel like for a beginner who discovers SketchUp’s API, they most likely have a specific idea they are really excited to figure out how to solve with code. But you’re basically telling that person to forget about their idea, go learn Ruby basics from some learning source that has absolutely zero context in 3D modeling, and come back later once they’ve made a bunch of boring practice programs solving imaginary problems. Only then are they “worthy” enough to play around with the SketchUp API.
I feel like it would be great if there were a path to learn Ruby within the context of SketchUp. That would be so much more engaging and interesting. It would drastically lower the barrier to entry. But idk, maybe there’s just not enough demand to justify someone creating something like that? Maybe most SketchUp developers are already programmers before diving into SketchUp…
I feel like that “Automatic SketchUp” book was a great attempt at teaching Ruby in the context of SketchUp, but I know you’ve pointed out many “incorrect” teachings in that book (plus at this point, it’s so old…)
That said Dan, I personally own several Ruby books, and have taken a course to learn the basics. My problem is I don’t practice frequently enough to gain proficiency, so there are gaps in my knowledge, and I suffer from I don’t know what I don’t know.
I suppose it would be helpful for me to think about specifically what I think could be improved, and provide that feedback…
When I first started out, the way I learned was by studying the code in existing extensions. That simultaneously covered both Ruby syntax and SketchUp Ruby API. But of course, there are two problems with that as a learning method: 1) there is no assurance that extension authors have followed good practices either in basic Ruby or in use of the SketchUp Ruby API, and 2) today so many extensions are encrypted to protect intellectual property that one can no longer usually learn from the masters.
SketchUp is their product and helping users learn it is part of their product evangelism.
This is not universal however. Some companies do this free and some (like Rhino for example) charge for learning resources.
“Worthy” is the wrong word. It’s “being educated” enough to produce a working and stable extension.
There is no magic wand we can wave and make instant programmers. Sorry.
But all the Core Ruby and Standard Library docs are external. Any contextual courseware would constantly be referring to external documentation and reproducing what is already out there. At least for the basics of programming such as file I/O, iteration, reflection, etc.
And I wish Mr. Scarpino would update his book and release a new edition.
Yes many users who are very busy doing architecture may not have the time to get proficient.
Several of us have talked about starting a cookbook type of repository linked into the Files section of the Ruby API documentation.
A few of the Trimblers were interested at first, but then I got the feeling that their managers above them did not want to spend any company time (ie, money) on this expansion of the documentation.
So then we do have several (Julia and Thomas) who publish their own example repos and gists on their own time. Although beneficial, this also contributes to the spread (rather than the consolidation) of learning resources.
I attempted to bring some link lists together in the Ideas section of the Ruby Resources, but it could use expansion.
These days, probably. Several years ago, I’m not so sure.
I see several reasons:
The old Ruby API documentation had its own issues (mainly, it was time-consuming for the team to maintain), but its structure more closely resembled how the end-user experiences SketchUp. I think it made it easier for SketchUp users to dive into the API.
As Steve already mentioned, there was no encryption, so we could look at the code of existing extensions and learn from there.
There were far fewer extensions, and SketchUp lacked essential tools. So there was a need for users to create extensions for their own workflows. Nowadays with the profusion of extensions, and SketchUp getting the essential features it lacked, there is less drive for users to create extensions. These days, if you need to create an extension that doesn’t already exist, it’s probably quite an advanced one.
While it’s not SketchUp’s “responsibility” to teach people programming, it is something that would benefit SketchUp long term and something I think a lot of us would want to do. We can’t do everything, but it would be good if we could help people get started.
We are already discussing showing how to set up developer tools like TestUp and SketchUp Rubocop in future dev meetups. Feel free to go through the installation/getting started notes and file an issue if there is anything that could need clarification or rephrasing. A fresh pair of eyes is very valuable to detect these potential threshold that we ourselves no longer see.
Speaking of sketchUp Extension examples, both ThomThom and I have a large number of open source extensions over at GitHub. Personally I’ve found it easier to understand such practical examples than the more “artificial” examples SketchUp has published.
My impression is that a lot of productivity extensions are created by “power users”. People who are not trained developers, but had some experience or took the time to dig into it. I’m one of them, I’m educated as a model maker, designer, illustrator, but poked into web design and got exposed to JS/PHP etc. So when I started working with SU and got exposed to extensions I found that “I can kindof understand these things. Maybe I can write something myself.”
That’s where we hope having examples we maintain can serve as more assertive examples. (hat being said, SketchUp have in the past offered a number of examples that would not have passed EW moderation. In general I’d vouch for most on our GitHub account.
That might be because EW defaults to encryption now. (I’m not sure why that is the case TBH.)
Personally I wished more extension developers would make their source for their free extensions available on something like GitHub (BitBucket, or GitLab) with an open source license. (I got a long backlog of adding an license to my older ones, but at least most of them are on GitHub now.)
Seeing more collaboration using tools such as GitHub is something I’ve wished the extension community would grow into. There’s a low of sharing and helping on the forums, but I really think there are great opportunities with collaborating via GitHub. It could also be a nice way to get introduced to extension development, contribute a fix or improvement to an existing extension. You’d help out someone who’ve spend their time making and maintaining something, and you get a change to get feedback from someone experienced.
You think the old docs were easier to understand? I’d like to hear what we might have lost over the time if that’s the case.
That’s an interesting thought. And kinda makes sense - there certainly seems to be an evolutionary explosion in the early days. But, I’m still finding a lot of ideas for new workflow improving extensions, my problem is that I have less spare time to execute them.
I agree. And I’d love to see it easier for people to get going with writing extensions. You see the patterning schools these, with programming becoming part of the curriculum. Being able to do some basic coding can help in many areas.
[quote=“Matt, post:7, topic:174348”]But idk, maybe there’s just not enough demand to justify someone creating something like that?
[/quote]
There is something to this. Teaching is hard, very hard. There’s a lot more users of SketchUp than there are developers. Thus it’s easier to justify dedicated resources for training for SketchUp itself than for an API. And to teach an API you need someone who is tech savvy and experienced. Hard to get someone with that background willing to do only training instead of working on the product itself.
So, we (Extensibility) got to work with some tighter constraints, we end up doing it all. We do the development, the support and making all the tools and documentation. Stretches us thin. Probably the biggest reason we tend to defer the basics of programming to existing material. And why I tend to link to the “Ruby in 20 minutes” as I hope that’s less daunting - you might eye some accomplishments without spending too much time outside of the SketchUp realm.
That being said, there is a lot of room for improvement. I’ve been advocating for us to spend some time to rework our portals, developer portal and API front pages. Making some focused efforts into making it easier to onboard. In addition to improving the existing READMEs, examples and guides, I’d love to make a series of videos breaking down the various tools and setups. That off source takes time, but I think it’s worth investing in this, as it’s key part of the platform. Releasing API features isn’t enough by itself.
I’m really glad you brought up this topic Matt. Because it confirms a few of my suspicions about barriers and opportunities we have. If you’re up for it I’d be keen on doing a video chat with you to pick your brain more in-depth.
Honestly, it’s been so long I can’t remember the specifics.
But my recollection is that the structure of the old docs tended toward a 1:1 mapping with the SketchUp UI/UX. Now, the structure of the new docs has a 1:1 mapping with the implementation (this is just the nature of how YARD works, there is not much you can do about it).
With SketchUp, we’re lucky that the API implementation is not too far off from the UI/UX (I hear it’s much worse for AutoCAD or Revit). But still, I think there are things that can be hard to understand for beginners. Frankly, I am so used to the API now, that I can’t give an example from the top of my head, but I remember feeling this strongly when the new YARD docs appeared.
Google “Automatic SketchUp” by Matthew Scarpino. It’s out of print, but the PDF is available for free. Here’s one link to the book.
My favorite book for learning basic Ruby is “Learn to Program” by Chris Pine. It’s funny, well written, and easy to follow. A great confidence builder!
I also have bookmarks to the current SketchUp API and the original “Pragmatic” Ruby online book. Yes, it’s out of date, but it still has 95% of what you need, and it’s super easy to search. (I can never remember exactly how to call a method, so I’m always looking them up in these two references.)
Last but not least, look at lots of open source code. ThomThom especially has plenty of good stuff out there that shows you good style and will help you to set up a proper SketchUp project.
My first forays into SketchUp API was from when an existing extension didn’t quite work the way I wanted, so I tweaked it. I had no Ruby knowledge, but I knew some code from my web developing days (PHP). I deciphered what was going on in an existing extension with reference to the SketchUp API, then wrote a few lines of my own. I really recommend that as an approach to learning - you get results quite quickly which is satisfying.
As you say though, there are so many extensions out there, and many are well polished, so the impetus for doing it isn’t as great as it used to be.
Having said that, I still come across times where I think “I wish I could automate this task”, so I think there is still room for tinkering.
It should be made more explicit perhaps that the .rbz files are actually zip folders, and if unencrypted, can be opened and edited. Happily, most of the simple ones are unencrypted. Perhaps we should encourage all extension developers with free extensions to keep their code unencrypted?
I’ve been wanting to see a github/gitlab/bitbucket field for extensions, so open source can be markes as such. And improve the extension submittion form to make it clearer the effect of encrypting - perhaps even review the current default-on state.
I think it would be a great idea to link the extensions page to the “developer’s page” on github. It would be a nice thing that can encourage that step from being a user to an extension developer.
Switching to YARD was necessary and overall a great thing! Thanks for your hard work in that regard.