Added a help page with API Documentation

I've done two things in this commit:

1. I've added a Help page, so the "Help" section on the aside is no
   longer just a link, but a proper page inside of Portus. For now I've
   added a couple of interesting links.
2. In development (and test) environments users will be able to access
   to `/api/documentation` which is a page generated by the Grape
   Swagger API gem. This way users can test first hand the API.

See #1372

Signed-off-by: Miquel Sabaté Solà <msabate@suse.com>

Gemfile

@@ -96,6 +96,7 @@ unless packaging?
     gem "database_cleaner"
     gem "md2man", "~>5.1.1", require: false
     gem "binman", "~>5.1.0"
+    gem "grape-swagger-rails"
   end
 
   group :test do

Gemfile.lock

@@ -158,6 +158,8 @@ GEM
     grape-swagger-entity (0.2.0)
       grape-entity (>= 0.5.0)
       grape-swagger (>= 0.20.4)
+    grape-swagger-rails (0.3.0)
+      railties (>= 3.2.12)
     gravatar_image_tag (1.2.0)
     guard (2.13.0)
       formatador (>= 0.2.4)
@@ -360,9 +362,9 @@ GEM
       activesupport (>= 3.0.0)
     simplecov (0.10.0)
       docile (~> 1.1.0)
-      json (>= 1.8, < 3)
+      json (~> 1.8)
       simplecov-html (~> 0.10.0)
-    simplecov-html (0.10.1)
+    simplecov-html (0.10.2)
     slim (2.0.2)
       temple (~> 0.6.6)
       tilt (>= 1.3.3, < 2.1)
@@ -453,6 +455,7 @@ DEPENDENCIES
   grape-entity
   grape-swagger
   grape-swagger-entity
+  grape-swagger-rails
   gravatar_image_tag
   guard
   guard-rspec

app/controllers/help_controller.rb

@@ -0,0 +1,6 @@
+# HelpController holds the methods for rendering the help pages inside of Portus.
+class HelpController < ApplicationController
+  # Main help page.
+  def index
+  end
+end

app/views/help/index.slim

@@ -0,0 +1,22 @@
+.panel.panel-default
+  .panel-heading
+    h5 Help
+  .panel-body.table-responsive
+    div
+      span
+        | Check one of the following topics:
+
+    br
+
+    ul
+      li
+        = link_to "First steps into Portus", "http://port.us.org/docs/first-steps.html"
+      li
+        = link_to "Explore all the features", "http://port.us.org/features.html"
+      li
+        = link_to "Frequently Asked Questions", "http://port.us.org/docs/FAQ.html"
+      li
+        = link_to "Configuring Portus", "http://port.us.org/docs/Configuring-Portus.html"
+      - unless Rails.env.production?
+        li
+          = link_to "API Documentation", "/api/documentation"

app/views/shared/_aside.html.slim

@@ -1,31 +1,33 @@
 aside
   ul
     li.active
-      a[href="#{url_for root_path}"]
+      = link_to root_path
         i[class="fa fa-dashboard"]
         | Dashboard
       - if current_page?(url_for root_path) || current_page?(root_path)
         .list-selected
     li.active
-      a[href="#{url_for namespaces_path}"]
+      = link_to namespaces_path
         i[class="fa fa-ship"]
         | Namespaces
       - if current_page?(url_for namespaces_path)
         .list-selected
     li.active
-      a[href="#{url_for teams_path}"]
+      = link_to teams_path
         i[class="fa fa-users"]
         | Teams
       - if current_page?(url_for teams_path)
         .list-selected
     - if current_user.admin?
       li.active
-        a[href="#{url_for controller: 'admin/dashboard', action: 'index'}"]
+        = link_to admin_dashboard_index_path
           i[class="fa fa-cogs"]
           | Admin
         - if current_page?(url_for controller: 'admin/dashboard', action: 'index')
           .list-selected
     li.active
-      a[href="http://port.us.org/documentation" target="_blank"]
+      = link_to help_index_path
         i[class="fa fa-life-ring"]
         | Help
+      - if current_page?(url_for help_index_path)
+        .list-selected

config/initializers/swagger.rb

@@ -0,0 +1,6 @@
+unless Rails.env.production?
+  protocol = ENV["PORTUS_CHECK_SSL_USAGE_ENABLED"] ? "https://" : "http://"
+
+  GrapeSwaggerRails.options.url      = "/api/swagger_doc.json"
+  GrapeSwaggerRails.options.app_url  = "#{protocol}#{APP_CONFIG["machine_fqdn"]["value"]}"
+end

config/routes.rb

@@ -7,6 +7,8 @@
   end
   get "/teams/typeahead/:query" => "teams#all_with_query", :defaults => { format: "json" }
 
+  resources :help, only: [:index]
+
   resources :team_users, only: [:create, :destroy, :update]
   resources :namespaces, only: [:create, :index, :show, :update] do
     put "change_visibility", on: :member
@@ -58,6 +60,7 @@
   end
 
   mount API::RootAPI => "/"
+  mount GrapeSwaggerRails::Engine, at: "/api/documentation" unless Rails.env.production?
 
   namespace :admin do
     resources :activities, only: [:index]

spec/controllers/help_controller_spec.rb

@@ -0,0 +1,18 @@
+require "rails_helper"
+
+describe HelpController, type: :controller do
+  describe "GET #index" do
+    let!(:registry)   { create(:registry, hostname: "registry.test.lan") }
+    let!(:user)       { create(:admin) }
+
+    before :each do
+      sign_in user
+      request.env["HTTP_REFERER"] = "/"
+    end
+
+    it "returns the page successfully" do
+      get :index
+      expect(response.code.to_i).to eq 200
+    end
+  end
+end

spec/features/help_spec.rb

@@ -0,0 +1,20 @@
+require "rails_helper"
+
+feature "Help page" do
+  describe "API documentation support" do
+    let!(:registry) { create(:registry) }
+    let!(:user)     { create(:admin)    }
+
+    before do
+      login_as user, scope: :user
+    end
+
+    scenario "A user can go to the API documentation", js: true do
+      visit help_index_path
+      click_link("API Documentation")
+
+      expect(page).to have_http_status(200)
+      expect(page).to have_current_path("/api/documentation")
+    end
+  end
+end

spec/views/help/index.html.slim_spec.rb

@@ -0,0 +1,8 @@
+require "rails_helper"
+
+describe "help/index" do
+  it "renders the page successfully" do
+    render
+    expect(assert_select("h5").text).to eq "Help"
+  end
+end