Readme contains broken links to documentation

[abonas]

the "more info" section contains several links to documentation, they seem to lead nowhere.
https://github.com/hawkular/hawkular-client-ruby#more-info

cc @josejulio

[josejulio]

All the links are meant to be seen in the context of yardoc [1]. Check first link on the Readme[2]

I though it because of this other link[3] on the Changelog section[4]. Compare with the one in the documentation[2].

One way to avoid this (i think) would be to create a separate Readme.md for github.

[1] https://github.com/hawkular/hawkular-client-ruby#generate-documentation
[2] http://www.hawkular.org/hawkular-client-ruby/
[3] https://github.com/hawkular/hawkular-client-ruby/blob/master/file.CHANGES.html
[4] https://github.com/hawkular/hawkular-client-ruby#changelog

[abonas]

link in item 3 above is 404..
and it should work on github as well since many users are reading the readme there.

[josejulio]

Yes, item 3 doesn't work on github but works on the Hawkular documentation[1]. I didn't do that, I just followed that behavior.
I'll check what can be done.

[1] http://www.hawkular.org/hawkular-client-ruby/

[jkremser]

The links are meant to work from the context of the generated yardoc. Unfortunately, the rdoc on github doesn't support those github directives (ifdef::env-github[]..) that work in adoc and markdown so we can't simple have one version for 2 purposes. Also now the documentation has to be generated and pushed to the gh-pages branch manually after the gem release and for the previous version the docs were missing.

So, we can make it work on the README on GitHub in the first place and also have a simple bash/ruby script that changes those 3 links in the generated yard docs, this would be done in travis only during the release. I guess, the release build can be recognized by some environmental variable in Travis, i.e we are building a tag and the tag has some x.y.z format. Also the travis would need to push the result of the yardoc back to the gh-pages branch, so there must be also some github token used + some magic.

If there is an easier way to do that, please leave a comment. Otherwise, I'll do the ^

[jkremser]

Also it'd be nice to have also older docs available on the website, not only the latest ones.

Something like:

• http://www.hawkular.org/hawkular-client-ruby/2.9.0/docs
• http://www.hawkular.org/hawkular-client-ruby/2.8.0/docs
• http://www.hawkular.org/hawkular-client-ruby/latest/docs

where latest is in fact a symlink to the 2.9.0, I am not sure if this works on github pages, but I can give it a try.