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.

[DanRathbun]

@jimfoltz

I go to: https://github.com/SketchUp/sketchup-yard-template
I can clearly see that there are a "pages" and an "assets" folder in the root.
They are identical to those same named folders, that are
in the https://github.com/SketchUp/ruby-api-stubs repo.

It's kind of a chicken and egg, which came first ?

I thought it must be the template, because it generates the stubs.

[DanRathbun]

@jimfoltz Just looked through all branches and these 2 folders are in every branch.

[jimfoltz]

I see. I thought you were talking specifically about the frame change observer and load handler documentation.

I would think that the items in the pages directory would be only in the stubs repo because they are generated.

I'm not sure how yard uses the assets directory

[DanRathbun]

No they are people written markdown files. And the ReleaseNotes.md need a major overhaul. They were just pasted into the .md. file, and do not render correctly. There is a issue filed for them already (I think.)

[DanRathbun]

@jimfoltz: I'm not sure how yard uses the assets directory

From the docstring, in the Sketchup::Color class, line 14:
# {include:file:assets/colors.html}

ADD: This is an authored html fragment, not a YARD generated html page.

[DanRathbun]

The whole point of my asking, is that I did the same thing with the build numbers.
Made a html fragment that has two nice tables wrapping the info.

I also separated the Release Notes into multiple pages, one for each major version.

[thomthom]

Yea, after I copied the YARD templates into the stubs repo that caused some duplications. Maybe they can be one and the same. Otherwise one have to manually set up things in order to build the docs from the stubs. I was thinking it was easier if people could just pull one repo and build the docs themselves.

And yes, the release notes are a mess. Copied from the old docs with minimal tweaks.

[DanRathbun]

@thomthom

Otherwise one have to manually set up things in order to build the docs from the stubs. I was thinking it was easier if people could just pull one repo and build the docs themselves.

I successfully built the docs locally using the template supplied with the stubs. I see in the template repo that there are quite a few branches.

(1) How do I know (or should I care,) what the branch is (for the template) inside the stubs repo ?

In the OP, you said:

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

(2) I only saw a master branch for the stubs, so I forked that and cloned it locally. Is this good so far ? (It built ok.)

[thomthom]

Ah, sorry, I recently merged it that dev branch back to master, forgot to update this ticket. For the template repo, the master is the main one to care for. The dev branches are work in progress.