@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.
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
includesyntax. 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
.rbfiles 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
@exampleblocks 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 ExamplesI think these render at the bottom of the docstring and maybe down near the @Version tag.