Ruby API Docs - Contributing


#21

@tt_su, the ruby-api-stubs project’s REAMDME says the name is “ruby-api-rubs”.


#22

Since we launched the new Ruby API docs last year we told people to submit issues in the GitHub repo that contains the generated docs.

But we are currently experimenting with accepting pull requests to the stubs repo; https://github.com/SketchUp/ruby-api-stubs

(More info: https://github.com/SketchUp/ruby-api-docs/issues/32)

If that seems to work, then we might make that repo the main one to report documentation issues. Right now things are in some flux as we experiment with various tools and solutions.


#23

@thomthom

https://github.com/SketchUp/ruby-api-stubs main page suddenly
has GitHub-wide search buttons above the file listing.

Why?


#24

@thomthom, okay, revise the above to say "ABOUT.md"
says “ruby-api-rubs” instead of “ruby-api-stubs


#25

That is something GitHub rolled out they are calling “Topics”.


#26

It is distracting, and I didn’t see it in any of the other API related repos,
so I thought perhaps it was something Thomas switched on (ie, an option.)

Oh and thank you for the answer !


#27

One has to manually add topics to a repo. Been adding these tags as I’ve been going along.


#28

Why? Why direct people to unrelated APIs elsewhere on GitHub, or unrelated “stubs” repos elsewhere on GitHub ?


#29

Think of it the other way around - directing people looking for “sketchup” and “stubs” to the repository.


#30

I don’t “get” it … I am already there, why would I need a button giving global search results with where I am already hidden somewhere in the list ?


#31

It for when you are not there. Think when you are at the github front page - and you type in “sketchup stubs” into the search fields. (Or even from google). It’s search optimisation.

The “sketchup” tag is probably the most important one, combine it with the more generic tags to find things related to SketchUp. Already found some interesting projects I’d not heard of already.


#32

But they do not appear on my GitHub homepage, nor your’s, which is where I’d think you’d want them to appear. It is still weird that they are where they are.

Are you saying that by putting them there, that other members global searches will be able to find this specific repo more easily ? (If so, I’d think such keywords would normally be hidden in the repo’s settings.)

Doesn’t make sense to me that they are there at the head of the repo. (I could agree if they were perahps in a sidebar menu, or down in the page footer where external links usually are.)


#33

Reminder that GitHub is overhauling their Terms of Service.
Comments closed at 5:00pm (PST) on Tuesday, February 21 (2017).

See:

The new terms were to be active on 28 February 2017.


#34

A head’s up: The new OneBox feature for the API documentation pages is now live.

(Thanks to Thomas Thomassen for merging the feature into the API documentation template.)

Any content site that support’s Open Graph or Twitter Card protocols, should be able to display a onebox by gathering meta fields from the page’s <head> section. The Discourse forum engine has OneBox support built-in (and a Ruby-on-Rails extension available.)

All that is needed is a URL on a line by itself, and the Discourse engine will use the URL to gather the meta information and display a OneBox. This information is gathered and display at the page level. (Direct URLs to specific API methods will not generate a OneBox.)
(EDIT: Actually such URLs will create a OneBox, as the plugin just ignores the anchor to the specific method, and displays the OneBox for the page.)

Note, that there must be no whitespace preceeding the URL (on it’s line) and that you may need a blank line before the URL to be “oneboxed”.


So, for example, pasting
http://ruby.sketchup.com
… on a line by itself, results in:

And, for example, pasting
http://ruby.sketchup.com/Sketchup/OptionsManager.html
… on a line by itself, results in:


#35

Thank Dan for making that happen. :thumbsup:


#36

(@sam, ping for interest)

Currently, the information comes from meta tags in the page’s <head> section, not from the <body> content.

Keep in mind that YARD doc page’s is new to “Oneboxing”, (ie I had to add in into the template,) … so having “oneboxed” links to content paragraphs (method descriptions) is not something that was thought about much when the OneBox was invented.


You could perhaps customize the OneBox plugin that this forum uses, but other sites would still just “box” the class or module pages’s data.

The individual method text would need to be wrapped in some kind of HTML or XML tag so that the OneBox plugin could parse the text out of the page’s source.


To fix your URLs just insert a space at the beginning of the line, and the link will not be “oneboxed”.


#37

There are different plugins? I thought this forum had a plugin that pulled from the metadata.
…I clearly need to read up on OneBox and how it works.


#38

For anchor links, the individual metadata would maybe need to be placed as attributes (microdata or RFDa) at the link element <a>, and the onebox would have to jump to the anchor and see if there is metadata other than in the head.

It seems open graph is not designed for multiple items on a page, and principles of semantic web would rather see a method as its own object, thus with its own URI.
https://stackoverflow.com/questions/29658632/facebook-open-graph-link
http://radar.oreilly.com/2010/05/facebook-open-graph-and-the-se.html

For Wikipedia and Github, they added anchor support in the respective onebox plugins. But there is no general solution (in the default onebox).
https://meta.discourse.org/t/support-wikipedia-anchors-in-onebox/19664
https://meta.discourse.org/t/feature-the-related-anchor-in-github-urls-with-only-one-line/19927


#39

I cannot see having to double all the data on the page. The YARD doc output is just not designed to do this kind of thing with the default template. So it would require a major overhaul of the template the API doc use.


#40

I’m starting to wish for a brand new template. The default YARD template is cumbersome to customize.