Doc generation cannot build docs relative to apidocs

[andrewnicols]

I asked a while ago on IRC about docs for older versions of YUI and the advice was to host our own. I've been looking at using the docs included in official release downloads. However, I've hit a minor snag.

The doc generation links to the official online API docs rather than the docs generated by the build. As an example on http://andrewnicols.github.io/moodle/docs/yui/3.13.0/docs/anim/index.html, the text "For more information on creating YUI instances and on the use() method, see the documentation for the YUI Global Object." links to http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_use rather than http://andrewnicols.github.io/moodle/docs/yui/3.13.0/api/classes/YUI.html#method_use. It's not a major issue, but it means that documentation will link to different versions.

Ideally, it should use a relative link.

[clarle]

@triptych @andrewnicols

This seems like a good idea. There's a fairly large amount of hard-coded full path links to http://yuilibrary.com in the source right now:

https://github.com/yui/yui3/search?q=http%3A%2F%2Fyuilibrary.com&ref=cmdform&type=Code

The alternative might be to still create the full path links, but be able to replace the root URL either through configuration or a command line argument during the documentation generation step.

[andrewnicols]

Thanks for the reply @clarle,

I'd actually argue that it should be the other way around - documentation distributed in the release should be built relative to the API docs, and for most people building docs on their own this is probably also what they want. I imagine that the only cases where this is not wanted is for the documentation on yuilibrary.com, but this should also just work with the relative path and the online docs are built differently in any case (to add search) so they're already a special case.

I did have a quick look at how this could be don last night, but alas it's not quite as simple as I'd first hoped. Because the links would need to be relative, and some docs are built at a different folder depth, we'd need to make allowances of the depth of the relative link. A lot of the occurrences of the the URL are because they're using the apiDocs variable, but we could rewrite these as a Handlebars helper instead, but my knowledge of Selleck and Handlebars isn't quite there yet to know whether this is a viable route.

I did have a play last night at patching selleck to take a list of helpers (from a helpers folder similar to the way in which partials are handled) and apply them, but then wasn't sure how best to write the helper to make the link relative (and couldn't access the options in order to get the variable).

Any thoughts on the above would be gratefully appreciated,

Andrew

[clarle]

@rgrove Any thoughts on this?

[rgrove]

YUI dist packages should probably use a relative URL for the {{apiDocs}} variable instead of an absolute URL. I think dist.json is the place to change this, but I haven't been involved in the building of dist packages in years, so I don't know what's changed: https://github.com/yui/yui3/blob/master/src/common/docs/dist.json

I left Y! and stopped maintaining Selleck before getting around to implementing helper support, but I think adding link generation helpers is the right way to go for solving this in the long term. Link helpers would make it easier to generate proper relative or absolute links to API docs and other Selleck pages.

[andrewnicols]

Thanks @rgrove,

Think I'm on the right track then. The dist docs are still built using dist.json and obviously it's incapable of handling relative link generation as it's only a variable.

I've mostly implemented helpers in selleck but haven't written unit tests. At the moment I've gone for the option of including the function using node's require and expecting the helper to export it's function for it to be registered but I'm not sure whether this is the best approach. Still need to work out how to write the helper...

Thanks for affirming,

Andrew

Sent from my iPhone

On 13 Nov 2013, at 08:22, Ryan Grove notifications@github.com wrote:

YUI dist packages should probably use a relative URL for the {{apiDocs}}variable instead of an absolute URL. I think dist.json is the place to change this, but I haven't been involved in the building of dist packages in years, so I don't know what's changed: https://github.com/yui/yui3/blob/master/src/common/docs/dist.json

I left Y! and stopped maintaining Selleck before getting around to implementing helper support, but I think adding link generation helpers is the right way to go for solving this in the long term. Link helpers would make it easier to generate proper relative or absolute links to API docs and other Selleck pages.

— Reply to this email directly or view it on GitHubhttps://github.com/yui/yui3/issues/1336#issuecomment-28348738 .