making YARD output machine-friendly?

[Rich Morin]

I'm wondering about the current status and near-term prospects for
making YARD output machine-friendly. For example, YARD pages could
include RDFa markup or a YARD server could emit JSON, on request.

This would allow Chrome Extensions (etc) to harvest the metadata,
re-organize and/or reformat it, etc. I'd like to know how folks
feel about this and what format(s) would be most reasonable and
useful to implement.


-r

--
http://www.cfcl.com/rdm Rich Morin
http://www.cfcl.com/rdm/resume r...@cfcl.com
http://www.cfcl.com/rdm/weblog +1 650-873-7841

Software system design, development, and documentation

[Loren Segal]

Hey Rich,

On 5/9/2012 3:50 PM, Rich Morin wrote:
> I'm wondering about the current status and near-term prospects for
> making YARD output machine-friendly. For example, YARD pages could
> include RDFa markup or a YARD server could emit JSON, on request.
>

Good question. JSON data has actually been brought up a few times for
search, as well as for building custom templates (we could theoretically
completely scrap our template API and have customizations be done via
JS). Theoretically, we could just do something like Ember.js and have
docs be a one-page app that just build off of a js file with all of the
object data in it. Doing this would actually cut YARD's runtime by
significant amounts, since generating HTML is the most expensive part of
the process right now.

There are performance issues with that though, so we never really went
that far into it. There are also some issues regarding how browsers deal
with "cross-domain" requests on local file:// URLs.

The hybrid solution seems like the best fit, having JSON output only in
the YARD server. This might be a better fit for a plugin right now
though, given that it's not really on our current priority list-- that
might change in a few releases. Figuring out exactly how to split up the
data would be the biggest concern, as serving it all at once would
probably bog down a JSON client. I suppose the best fit would be to list
content per namespace. Again, these decisions are easier if they are
left out of core, so if you can come up with a plugin, that would be
probably be useful. rubydoc.info could certainly install it.

Loren

[Rich Morin]

Initially, of course, this sort of thing should be a plugin
or some other sort of opt-in feature. However, once we have
a proof of concept for an end-to-end solution, I'd really
like machine-friendly output to be available by default.

Without widespread availability for machine-friendly output,
there is little incentive to create browser extensions and
other follow-on tools. Can we sketch out a road map and a
set of criteria that would let us get to "real" deployment?

[Loren Segal]

On 5/9/2012 8:28 PM, Rich Morin wrote:
> Initially, of course, this sort of thing should be a plugin
> or some other sort of opt-in feature. However, once we have
> a proof of concept for an end-to-end solution, I'd really
> like machine-friendly output to be available by default.

Well, "by default" isn't really the biggest concern right now.
Practically speaking, I don't know of (m)any sites besides rubydoc.info
that host the YARD server, so that's the primary place it needs to be
deployed (which as I mentioned can be easily done if the code exists).
Offline servers running on local machines would be useful, but I don't
think there's going to be a significant amount of users who will be
needing that just yet. And requiring a "gem install yard-server-json"
probably wouldn't be a big barrier to entry.

> Can we sketch out a road map and a
> set of criteria that would let us get to "real" deployment?

Honestly, I don't really know what your criteria is, so you probably
know best about this. My assumption would be to just dump whatever is in
the db for each object out to json capturing all ivar data in some
json-friendly format.

There doesn't need to be much roadmapping for this. Implement it and if
it works, it will be used.

My only suggestion would be to use YARD server's "routers" to prefix a
/json/ route rather than suffix URLs with '.json'. The server arch can't
handle the latter, because ".json" could actually be the URL for a class
method on a class object (like: /foo/bar/JSON.json). See the route
prefixes in YARD::Server::Router

Loren

[Rich Morin]

Thanks for the clarification. I'll look into defining a JSON-based
API (possibly using JSON-LD) and report back. Assuming that this
gets your general approval, I can look into hacking up a plugin.

[ahmad....@gmail.com]

My apologies for resurrecting a three year old topic. Did this get anywhere?