Ruby API Docs - allow community docs?

[MSP_Greg]

When one goes to http://ruby.sketchup.com/ and clicks on ‘Files’ in the list pane, the list could easily contain several more items without needing to be scrolled.

1. Would Trimble allow ‘user created’ content to be placed there? Maybe the content could reside in a different repo, with all docs being markdown / .md format? Maintainers of the repo (commit rights) could be both Trimble staff and others.

2. I don’t know how much work it is updating the API site. Obviously, every commit to a docs repo would not justify regenerating the API site. Since GitHub renders md files well, one could always go to the repo for the most current info.

The kind of information I’m speaking is falls into two categories.

First, simple guides to things like Html and Web dialogs, maybe a description of event flow with tool plugins, maybe info about observer issues, etc.

Secondly, one or more reference doc’s with information about SU version and OS info.

Things like tables with Ruby version, HtmlDialog CEF version, browser versions used by WebDialog, JScript capabilities (arrow functions, etc).

Some (but not all) of this info is contained in the ‘Release Notes’, but it’s knd of a PITA to go thru it.

Thoughts?

@thomthom - I assume this would probably get added to your responsibilities, so wadda ya think?

JFYI, if this was implemented tomorrow, I couldn’t work on it for a week or two.

Also, with YARD, the .yardopts file can take absolute or relative paths for the docs list, so it can include docs/files from outside the normal code directory. I use it for many of the repos I doc that have separate ‘wiki’ repos…

[thomthom]

@MSP_Greg

Would Trimble allow ‘user created’ content to be placed there? Maybe the content could reside in a different repo, with all docs being markdown / .md format? Maintainers of the repo (commit rights) could be both Trimble staff and others.

We have been talking internally about adding more pages to the Files section. For stuff like explaining how the model hierarchy in SketchUp works (common questions from new developer - especially those working on importer/exporters). And other concepts such as material and layer inheritance.

@MSP_Greg

I don’t know how much work it is updating the API site. Obviously, every commit to a docs repo would not justify regenerating the API site. Since GitHub renders md files well, one could always go to the repo for the most current info.

Since the documentation need to be generated from our internal source we cannot open that up directly. But our Ruby API Stubs repo works as a public mirror: GitHub - SketchUp/ruby-api-stubs: Auto-generated stubs for the SketchUp Ruby API. Useful for IDE intellisense and auto-complete.

We have experimented in the past of accepting documentation fixes from that repo. I had a script that tried to compare diffs from that repo and backport them into our internal source. But it’s been very fragile and is currently broken.

But for the pages it’s easier, as we can just copy+paste them back to our internal source tree.

@MSP_Greg

First, simple guides to things like Html and Web dialogs, maybe a description of event flow with tool plugins, maybe info about observer issues, etc.

For guides and examples we have a separate repository:

GitHub - SketchUp/sketchup-ruby-api-tutorials: SketchUp Ruby API Tutorials...

For the HtmlDialogs - they quickly gets complicated so we have a special repository for that:

GitHub - SketchUp/htmldialog-examples: Examples of using SketchUp Ruby API's...

At the moment there’s a reference to the general example/tutorials from the docs’ README. But we should make sure to add links within the relevant class descriptions.

And we can create a separate overview page in the documentations.

It’s a lot easier for us to maintain and update the large examples and guides when they are separate repositories - not tied to our internal source.

[MSP_Greg]

@thomthom

We have been talking internally about adding more pages to the Files section…
<clipped>

above sounds like a ‘yes/maybe’, but other parts seem like a no.

@thomthom

It’s a lot easier for us to maintain and update the large examples and guides when they are separate repositories - not tied to our internal source.

Sorry I wasn’t clearer. Docs included in the YARD generated set do not need to be within your ‘internal source’ tree. They can be in a separate repo(s), you just need a fork of the docs repo in a separate folder on the system generating the API docs. IOW, if your internal source has a root folder, the docs can reside in another folder outside of it.

JFYI, you might want to edit the README in the SketchUp/sketchup-ruby-api-tutorials repo. ‘Fork’ can only be done with a repo, not folders within it.

[thomthom]

@MSP_Greg

They can be in a separate repo(s), you just need a fork of the docs repo in a separate folder on the system generating the API docs.

Good point.

[MSP_Greg]

Thom,

Hope you had a good vacation. Now, back to work!

I’ll see if I can get a start on some md files with content I’d like to see. Obviously, there could be some content that’s directed towards ‘getting started’, both for ‘new to programming’ or ‘new to programming in SU’. The release notes have a lot of the info, but it would be nice to have tables by subject. Things like:

Ruby version by SU version

JS/HTML issues by OS & SU version, may require separate tables for HtmlDialog and WebDialog.

Or, enough to answer questions like "I want to use HTML grids or JS arrow functions or some new Ruby functionality or (insert something else), what SU vers/OS combinations do I no longer maintain compatibility with?