RightScale Praxis Docs Plugin

This plugin includes a number of Praxis Doc Browser customizations that give your docs a distinctly RightScale identity. All Praxis apps in production with customer facing docs should be using this plugin. This also allows us to modify these assets conveniently in a single place rather than pushing to multiple repositories.

Installation

Add this line to your application's Gemfile:

gem 'rs-praxis-docs'

And then execute:

$ bundle

Or install it yourself as:

$ gem install rs-praxis-docs

Finally you will need to tell Praxis to load your plugin. This you can do in your app config block. (This often resides in config/environment.rb, but this can vary from app to app):

application.bootloader.use RSPraxisDocs::Plugin

Installing into an app that already has customizations

Generally speaking, you can remove the following from your docs directory:

all angulartics-* files
the following images:
- favicon.ico
- icon-caret.svg
- icon-email.svg
- icon-feedback.svg
- icon-phone.svg
- logo.svg
docs/layout.html
docs/navbar.html

Then you can make your app.js angular.module call look like this:

 angular.module('DocBrowser', ['RSPraxisDocBrowser'])

Finally your styles.scss should look like this:

 @import "rs-praxis-doc-browser.scss";

Installing in a vanilla praxis app

Change your app.js code to look like this:

 angular.module('DocBrowser', ['RSPraxisDocBrowser'])

Change your styles.scss to look like this:

 @import "rs-praxis-doc-browser.scss";

Usage

I recommend reviewing the app carefully before publishing. Pay attention to the following items:

[ ] Make sure that the correct app is highlighted as selected in the API selector menu:

If it isn't selected, you will have to add a name directive matching that name into your global API info block.
[ ] Make sure the code examples work by going to each action page and clicking the cURL button. If nothing is shown and you get an error in the console, remember that you must specify an endpoint directive in your global API info block.
[ ] Make sure the examples are correct and sensible. The default generator should do a good enough job, but isn't perfect. You can override a particular example by adding an docs/examples.json file that should look a bit like this:
```
  [
    {
      "type": "curl-sh",
      "resource": "MyResource",
      "action": "index",
      "example": "<pre>curl https://myapi.com/test -i -b rightscalecookies</pre>"
    }
  ]
```
resource and action should match what's displayed on the relevant action page.

If the examples don't work much in general, you can disable them globally by adding .constant('RSExamplesEnabled', false) in to docs/main.js.