search

SketchUp / sketchup-yard-template

YARD Template used to generate SketchUp Ruby API documentations
MIT License
13 stars 5 forks source link

Onebox support for API doc pages for forums etc. #18

Closed DanRathbun closed 7 years ago

DanRathbun commented 7 years ago

Onebox support for API doc pages for forums etc.

The object is to get a onebox post in the forum, that would look like:

+---------------------------------------------------------------------+
| ruby.sketchup.com                                                   |
|                    Class: Sketchup::ComponentDefinition             |
|       (icon)                                                        |
|                    (SketchUp Ruby API Documentation)                |
|                    The ComponentDefinition class is used to define  |
|                    the contents for a SketchUp component.           |
|                    Components are a collection of entities that can |
|                    be instanced and reused multiple times ...       |
+---------------------------------------------------------------------+

These files go in the "default/layout/html/" folder: (4th edition)

NOTE: These 3 files have changed again in the latest commit to the PR #19

embed_meta.erb.txt headers.erb.txt layout.erb.txt

I rearranged some things in the erb files so that everything in the page's <head> element are in a better order, and added some comments as section labels. (Aids when debugging,... helps you find stuff quickly.)

I am not sure how docstring text should be handled. At the top of the erb I'm doing this: ... [snip] ... (massively overhauled, see latest files.)

(1) The docstring.gsub(/[{}+]/,'') call is removing any RDoc or YARD markup delimiters. (Like {SomeClass} or +code+.) Any others may also need to be added to the RegExp.

(2) I am not sure how to force a linefeed in the OneBox description output. (I just stuck a "&#13;" in there now.) UPDATE: I gave on this, and just use the YARD built-in docstring.summary() method. (Why over complicate?)

REFERENCES:

The Open Graph protocol

Twitter Cards Developer Documentation

https://github.com/discourse/onebox#adding-support-for-a-new-url

http://oembed.com/

https://github.com/iamcal/oembed

thomthom commented 7 years ago

Cool - this would be a nice enhancement.

(2) I am not sure how to force a linefeed in the OneBox description output.

You think it's even supported?

DanRathbun commented 7 years ago

You think it's even supported?

Not sure. It's built-into Discourse, but the public OneBox plugin is meant as an addition to other people's websites running Rails, I suppose. I didn't look all thru it's code, and I'm not even sure the code is the same. (Ie, have they diverged?)

I was thinking more generally of how HTML would be rendered. If a client engine sees a "&#13;" will it render a linefeed ??

This isn't all that important (to have the title (SketchUp Ruby API Documentation) on the first line, as it will be the tooltip when hovering over the url, anyway. And readers of forum threads are likely to be in a Ruby category or Developer sub-forum anyway.

I just thought it might be a nice touch.

Now I think from what I have read, that there is the generic class(es) of OneBox, and system coders can write a custom OneBox subclass if it is wished to display the data in a special format.

Initially, I'd just like to test and see if the GenericWhitelisted OneBox will display on the forums, if a test class page (pick one near the top like Animation,) is given the proper meta tags.

DanRathbun commented 7 years ago

Now, down the road,... I was thinking that it'd be really cool, to paste a some_url#method url into a forum post, and a OneBox specific to that method would be rendered in the forum thread.

So the OneBox might show the argument list for the method (or even specific overload,) and serve as enough of a reminder or prompt, that the reader need not even go to the API page.

(P.S. - This idea was triggered as I was adding method specific "permalinks" to the template.)

DanRathbun commented 7 years ago

Okay, Sam Saffron told us that all we need do for Discourse (and other Open Graph capable sites,) is put the og <meta> property tags in the <head> element, per the protocol spec: http://ogp.me/

So having now read the spec, I updated the example erb file in the first post accordingly. (I already had most of them in there, but now I know what each means and is supposed to be, as well as how to properly set the image size.)

DanRathbun commented 7 years ago

And I added the link to the Twitter Cards Developer Documentation to the first post.

The API pages would use the Summary Card type, I believe. https://dev.twitter.com/cards/types/summary But I could not find a specific Twitter site just for the API(s) (or developer.sketchup.com), so it's currently just set to: "@sketchup". (The docs say "The Twitter @username the card should be attributed to. Required for Twitter Card analytics.) Also says the image should be 120x120 (... so, updated ERB, again.)

Once the tags are live, you can test your Card using our Twitter Card Validator. http://cards-dev.twitter.com/validator

DanRathbun commented 7 years ago

For the description, I think we should gave the first two sentences of the first paragraph only.

But what divides the paragraph in the docstring ?

Do they have embedded "\n" or "\r" ?

thomthom commented 7 years ago

Sorry for slow responses - I'm a bit swamped in tasks right now. I'll get back to this and have a closer look soon.

DanRathbun commented 7 years ago

That is Okay, I am still working out the kinks of this.

(I'm posting here as a means of "thinking out loud". You know, "talking points".)

I have not yet figured out how to access the current class' docstring whilst parsing the "layout.erb" and "headers.erb" files.

"object" and "owner" are just the bare name of the output file, ie "_index.html", so I cannot call object.docstring(), as it's a String class NoMethodError exception.

It is so confusing as to what properties and methods are valid at any one time. It seems that YARD defines alot of stuff globally within the "main" Objectspace ?

thomthom commented 7 years ago

Yea, I'm not sure what it's doing, it's either including into the global space, or it's loading stuff outside of Ruby's normal loading mechanism (eval-ing into its namespace?) Lots of meta-programming here which isn't obvious in terms of understanding code flow.

DanRathbun commented 7 years ago

Just a "heads up", ... I have solved all this and it is working well now.

Basically I had to study the code, read the whole dang manual twice, and then study the docs for many of the base YARD classes. What was throwing me off, was the author was using references (like object,) for disparate types of things, depending upon situation. Ie, it was not ref'ing a codeobject if the page was an index or a file page, ... instead he was using it to point at say a string like "_index.html". (I myself try not to do this and discourage others from doing it, as it always leads to unexpected TypeError and NoMethodError exceptions.)

I'll post the updated erb files into the original post as "4th edition" later tonite.

DanRathbun commented 7 years ago

Okay, 4th edition posted.

I gave on embedding a carriage return in the description, and just use the YARD built-in object.docstring.summary() method. (Why over complicate?)

It is a pain how GitHub will not allow erb posted, and says it allows zip, but dropping a zip containing file(s) with an erb extension results in a "we don't allow that type of file error". So I am forced to add a ".txt" to the end of all the filenames.

thomthom commented 7 years ago

So are the files in the OP all that is needed to add support for this for the docs? Could that be a PR?

(For posting snippets you can use gists: https://gist.github.com/)

DanRathbun commented 7 years ago

Yes they are. Yes it could. I guess you wish to be able to see diffs. It'll take a few days as my local repo is in another state for a navigational PR. For this "one-box branch", I just copied the original "su-template" and made the changes to those 3 erb files.

DanRathbun commented 7 years ago

It'll take a few days as my local repo is in another state for a navigational PR.

Actually, I was incorrect. My local "template" repo was in the original cloned state from SketchUp "master". I had really been "playing and testing" in the local stubs repo, so all it took was a new branch and then copying the 3 files between local folders.

Here's the PR. I followed your convention and named the branch "dev-onebox-meta-html".

DanRathbun commented 7 years ago

Closing this sice it is merged: https://github.com/SketchUp/ruby-api-docs/commit/322290730fa3ac7c95c47d4d23954c1fba74a57b

We'll add new issue(s) if there is need for tweaking.