Skip to content

dreamcat4/yard-slipstream

Repository files navigation

yard-slipstream

Small-to-meduim facelift on the default yard template. This yard plugin aims is to make yard documentation as clear and concise as possible. If you ever found yard documents were a bit hard to read, but of a strain. There arent many new features in this template. A few bug fixes.

So go on, lets give yard a styleover.

Demo

dreamcat4.github.com/plist4r

Usage

gem install yard-slipstream
  • Generate your documentation with yard as per the nomal process. For jeweler, then ‘rake yard`. The plugin is auto-loaded from rubygems. If you use bundler in your project, Bundler wont load this plugin automatically. So it must be added it to your projects `Gemfile`.

  • This template is 100% compatible with yard version ‘0.5.4`. So for the safe road, use with `yard 0.5.4`. Other versions of yard are also known to in variying degrees. (0.5.3, 0.5.5, etc).

  • Yard-slipstream doesnt work on yardoc.org. Sorry. For technical reasons its not possible, although there may be future plans to eventually open up yardoc.org. We recommend to generate your docs locally, and push them up to github / gh-pages. Your docs should still do everything that they would on yardoc.org, including Search.

Improvements

  • Blue search box to replace 3 seperate drop-down menus (Files List, Methods List, Class List)

  • The blue Search box is similar as per yardoc.org, but positioned in top-right corner

  • New backend to power the search box (loads onfocus a local json file ‘search_index.json’)

  • Best as-can-be-done html frames support

  • New Frames | No Frames hyperlinks bar. Top right, next to search.

  • Internal links stay in frames. External page links break out of frames.

  • ‘_index.html’ renamed to ‘object_index.html’. To avoid conflicts with jekyll / gh-pages

  • The above fix allows yard docs to be nestable within gh-pages / jekyll website

  • Better scrolling to embedded page links (yard issue-102)

  • Certain object navigation links emphasized (easier to click on / better prominence)

  • More rdoc-like method navigation (via the method ribbons)

  • A couple of sections re-ordered to work better in the new layout

  • Enables the info box for Top Level Namespace

Whats left the same?

  • Same basic fundamental layout. Which was already good to begin with.

  • Well, all of the other best aspects / detail from the original yard template. (We hope!)

  • We havent intentionally broken any features of yard. We promise.

Browser Compatability

Developed on Firfox and Safari. AFAIK Chrome and any other WebKit based browsers should be fine. Opera was not tested particularly thoroughly. This plugin isnt tested on IE (any version). Internet Explorer will probably show some inconsistencies, given how poorly it supports CSS. If anyone would like to contribute compatability fixes for either Opera or IE, please do so. You are more than welcome. Also please note that by adding new features, future compatablility may suffer.

Future compatibility / Support

  • The default yard template is a moving target, it changes on pretty much every new patch release.

  • This is a plugin to change the asthetics, and therefore it depends heavily on overriding the default yard template.

  • Some overrides may block future new features of yard becoming visible until the template is updated. This is usually pretty easy to fix. Just a straightforward merge of the new yard code.

  • Send me a pull request. Bonus points for describing what it fixes.

  • Of not, raise me an issue. Thanks.

Copyright © 2010 Dreamcat4. See LICENSE for details.

About

Streamlined Navigation with the default yard template

Resources

License

Stars

Watchers

Forks

Packages

No packages published