Extra Examples Wikis and Index

[DanRathbun]

@thomthom: ... I think that [ large code examples ] would fit better in a wiki page.
We can use the wiki features of GitHub repost o create a page -
then refer to a possible solution to the known bug from the doc.

Yes, in my old "play" repo, I have a "code" folder, and beneath that a folder for every module and class (following normal namespacing,) ... each folder contains rb scriptlets that are for inserting into the docs using the include syntax. Ie, something like this:
{include:file:code/SketchUp/Face/get_texture_projection.rb}

It's just that it was bugged before, when these includetags are in the class / method comments.

However, I never had any problem inserting external files using {include:file:} from within wiki markdown files.

The beauty of external .rb files is that they can be written, tested and edited, etc., at anytime using Notepad++, RubyMine or whatever code editor you like. (It is a real pain in the butt, embedding code examples into the class and method comments, if it's anything substantial. Like more than a few lines.)
I would really prefer that any @example blocks be from inserted scriptlets.

---

So, anyway, would any examples be better put into the sketchup-api-tutorials repo ?
If they were, could they be linked from the docs ?

Or would you rather just add a root "code" folder, and then any embedded example links could use the @see (See also: link description) tags ? {... at least for now.]

---

I'd really like to have a collapsible sub-section labeled Other Examples >, that when clicked would expand to a bullet list of extra example links.

I suppose for now it might be better to have a example index markdown page. Then, whenever a class or method gets a related extra example, we can add an a "See also:" tag:
@see ../pages/ExampleIndex.md Other Examples
I think these render at the bottom of the docstring and maybe down near the @Version tag.

[thomthom]

Yea, the api-tutorials repo would be one option. Though, that last idea of yours sounds interesting as well. Maybe that would be good for examples tightly coupled to the API docs (for explaining workarounds for bugs.)