Testing out pull request contributions

[thomthom]

We created a tool that will try to take a Pull Request to our Ruby API stubs and merge it back to our original C++ source where we generate the docs from.

At the moment the tool is highly experimental. If anyone would like to help in testing it let us know. We can start with a few changes to a class. It might be wise to not do too many changes in a Pull Request right away - in case the merge tool require changes.

Clone the master branch - it includes the YARD template and YARD options to allow you to locally generate the docs for your own testing.

[thomthom]

@jimfoltz - would you be willing to make a test Pull Request? (To the stubs repository.)

[jimfoltz]

Just added a simple pull request.

[DanRathbun]

@thomthom: We created a tool that will try to take a Pull Request to our Ruby API stubs and merge it back to our original C++ source where we generate the docs from.

(Musing Rant)

What a vicious circle !

I don't understand why you'd even want to do the return trip, and generate from the C++, when you can just generate from the API stub repo.

Having the end user documentation embedded in internal code (the C++ core) just bloats your code and slows down everything. The core programmers have to wade through and around all that end user comment junk all the time to do their work.

(Back to Normal)

Question: What happens if we want some documentation of a class that is NOT defined by your C++ core code ? How will you exclude this extra information from being inserted back into your codebase ?

Do we need to define some custom YARD tags, ie @ignore or whatever, to filter upon ?
(Perhaps use the @apitag with some certain label, ie: @api ignore)
See: YARD: Adding Custom Tags

Example I myself had created a custom @ruby (hidden, transitive) tag in my .yardopts file, to mark modules and classes that were from the Ruby Core, by adding in these lines:

--name-tag ruby
--transitive-tag ruby
--hide-tag ruby

Custom YARD tags can be used for filters.
See: YARD: Usage - Queries

[thomthom]

Question: What happens if we want some documentation of a class that is NOT defined by your C++ core code ? How will you exclude this extra information from being inserted back into your codebase ?

We already have this scenario, with the Tool class for instance, it's not really defined by the API. I think the FrameChangeObserver is the only one left like that. Which I think should be extracted to it's own page like everything else. We'll just add the appropriate corrections on our side to get the incorporated.

[DanRathbun]

@thomthom: We already have this scenario, with the Tool class for instance, it's not really defined by the API.

No, I'm speaking of modules and classes that are extra API. For example some of the core mixin modules (Kernel, Comparable and Enumerable,) and core base classes, (ie, Float, Integer, etc.) Why ?
I'm weary of explaining to noobs that the API collection classes have the Enumerable methods via composition, and all other objects have Kernel and Object methods via inheritance.
Secondly, it's a bummer having to open another browser tab, just to go lookup some core Ruby method.
Thirdly, I (along with others) loath how the core doc's Rdoc template creates the online core pages. The left column navigation boxes are static and scroll away out of sight, and are in a weird order. Neither they, nor the main content sections are collapsible.
So, in my doc set, I am adding files for these modules and classes. This way I can lookup core Ruby class information, using the much better YARD generated interface.

So this is case (A). What do you need to do to ignore some Ruby core class or module file, so that it doesn't bloat your C++ files ? (Perhaps an --exclude tag in the "yardopts" file ?)

[DanRathbun]

Now what I was wondering for case (B) (being extra external files, that likely will appear on the "Files" page.) These would be diagrams and other extraneous information likely authored in markdown. Included are the API Introduction, Build Number Tables, Release Notes, FAQs, etc.

Looking at the current "ruby-api-docs" repo, I see that it contains only the ruby stubs. So this part (B) is moot as far as my previous worry about overloading your API core source files, but brings up another question:

But, how would we contribute to the extra files, when there is no repo for them ?

[DanRathbun]

@thomthom: I think the FrameChangeObserver is the only one left like that.

Actually, not.

The LoadHandler is another abstract class that is documented all within a method treatment. In this case, it's the Sketchup::DefinitionList#load_from_url() method.
See: http://ruby.sketchup.com/Sketchup/DefinitionList.html#load_from_url-instance_method

[thomthom]

Ah, yes the LoadHandler. We should get that listed as well. So far I placed these abstract classes under the Sketchup namespace. Even though they don't really exist there. But just for the sake of indicating "ownership".

With FrameChangeObserver we could have documented the add_frame_change_observer with a @param [#showFrame] tag, and avoid the whole separate class thing. Because that all what that method cares about. But, a separate page for this virtual class makes it more discoverable?

I'm tempted at adding a custom tag we can use to indicate that these classes are "virtual" - no real base implementation.

As for the non-SketchUp-API classes, I think we'll put that on hold for a bit while we get the SketchUp API docs cleaned up. Want to get these repositories and workflows stabilized before expanding much more to them. I think Greg (?) had done something similar for his own YARD template, combining all the docs. Worth its own issue we can track?

[DanRathbun]

@thomthom: I'm tempted at adding a custom tag we can use to indicate that these classes are "virtual" - no real base implementation.

No need. YARD has the @abstract tag, and I added it right at the top.

It puts a boxed warning right at the top just below the "Overview" heading, that says by default "This class is abstract." But the tag also takes text that will be appended.

Ref: http://www.rubydoc.info/gems/yard/file/docs/Tags.md#abstract

[DanRathbun]

@thomthom: I think Greg (?) had done something similar for his own YARD template, combining all the docs. Worth its own issue we can track?

Yes I liked how his worked. I just do not wish to have to download the whole Ruby Core source and have that in the API repo. (I think I generated stubs using Ruby's reflection/introspection.)

We can hold off with the issue logging for now.

[DanRathbun]

@thomthom

@DanRathbun: But, how would we contribute to the extra files, when there is no repo for them ?

I see that they are actually within the sketchup-yard-template project's pages and assets folders.

[DanRathbun]

@thomthom ... actually, they are also in the sketchup-yard-stubs repo.

Would we add them there and then the template repo copies them ?

[jimfoltz]

They don't belong in the templates repo, and I actually do not see them in the template repo on any branch.