start working on general docs

docs/00_overview.md

@@ -0,0 +1,7 @@
+# Overview
+
+... some general docs here ...
+
+## Media Types
+
+The API is currently JSON only.

docs/01_cross_origin.md

@@ -0,0 +1,23 @@
+# Web Clients
+
+When write an in-browsers client, you have to circumvent the browser's
+[same origin policy](http://en.wikipedia.org/wiki/Same_origin_policy).
+Generally, we offer two different approaches for this:
+[Cross-Origin Resource Sharing](http://en.wikipedia.org/wiki/CORS) (aka CORS)
+and [JSONP](http://en.wikipedia.org/wiki/JSONP). If you don't have any good
+reason for using JSONP, we recommend you use CORS.
+
+## Cross-Origin Resource Sharing
+
+... some general docs here ...
+
+In contrast to JSONP, CORS does not lead to any execution of untrusted code.
+
+Most JavaScript frameworks, like [jQuery](http://jquery.com), take care of CORS
+requests for you under the hood, so you can just do a normal *ajax* request.
+
+Our current setup allows the headers `Content-Type`, `Authorization`, `Accept` and the HTTP methods `HEAD`, `GET`, `POST`, `PATCH`, `PUT`, `DELETE`.
+
+## JSONP
+
+... some docs here ...

lib/travis/api/app/endpoint/documentation.rb

@@ -11,7 +11,12 @@ class Travis::Api::App
       get '/' do
         content_type :html
         endpoints = Endpoints.endpoints
-        erb :index, {}, :endpoints => endpoints.keys.sort.map { |k| endpoints[k] }
+        erb :index, {}, endpoints: endpoints.keys.sort.map { |k| endpoints[k] }
+      end
+
+      get '/x' do
+        content_type :html
+        general_docs
       end
 
       helpers do
@@ -38,6 +43,29 @@ class Travis::Api::App
             gsub(/<\/?code>/, '').
             gsub(/TODO:?/, '<span class="label label-warning">TODO</span>')
         end
+
+        private
+
+          def general_docs
+            @@general_docs  ||= doc_files.map do |file|
+              header, content = File.read(file).split("\n", 2)
+              content         = markdown(content)
+              subheaders      = []
+
+              content.gsub!(/<h2>(.*)<\/h2>/) do
+                subheaders << $1
+                "<h2 id=\"#{$1}\">#{$1}</h2>"
+              end
+
+              header.gsub! /^#* */, ''
+              { id: header, title: header, content: content, subheaders: subheaders }
+            end
+          end
+
+          def doc_files
+            pattern = File.expand_path('../../../../../../docs/*.md', __FILE__)
+            Dir[pattern].sort
+          end
       end
     end
   end
@@ -118,6 +146,13 @@ __END__
           </div>
           <div class="well" style="padding: 8px 0;">
             <ul class="nav nav-list">
+              <% general_docs.each  do |doc| %>
+                <li class="nav-header"><a href="#<%= doc[:id] %>"><%= doc[:title] %></a></li>
+                <% doc[:subheaders].each  do |sub| %>
+                  <li><a href="#<%= sub %>"><%= sub %></a></li>
+                <% end  %>
+              <% end  %>
+              <li class="divider"></li>
               <% endpoints.each  do |endpoint| %>
                 <li class="nav-header"><a href="#<%= endpoint['name'] %>"><%= endpoint['name'] %></a></li>
                 <% endpoint['routes'].each  do |route| %>
@@ -163,18 +198,29 @@ __END__
 
         <section class="span9">
 
+          <% general_docs.each  do |doc| %>
+            <%= erb :entry, locals: doc %>
+          <% end  %>
+
           <% endpoints.each  do |endpoint| %>
-            <div id="<%= endpoint['name'] %>">
+            <%= erb :entry, {},
-              <div class="page-header">
+              id: endpoint['name'],
-                <h1>
+              title: endpoint['name'],
-                  <a href="#<%= endpoint['name'] %>"><%= endpoint['name'] %></a>
+              content: erb(:endpoint_content, {}, endpoint: endpoint) %>
-                </h1>
+          <% end  %>
+
+        </section>
       </div>
-              <% unless  endpoint['doc'].to_s.empty? %>
+    </div>
+  </body>
+</html>
+
+@@ endpoint_content
+<% unless  endpoint['doc'].to_s.empty? %>
   <%= docs_for endpoint %>
   <hr>
-              <% end  %>
+<% end  %>
-              <% endpoint['routes'].each  do |route| %>
+<% endpoint['routes'].each  do |route| %>
   <div class="route" id="<%= slug_for(route) %>">
     <pre><h3><%= route['verb'] %> <%= route['uri'] %></h3></pre>
     <% if  route['scope'] %>
@@ -184,12 +230,15 @@ __END__
     <% end  %>
     <%= docs_for route %>
   </div>
-              <% end  %>
+<% end  %>
-            </div>
-          <% end  %>
 
-        </section>
+@@ entry
+<div id="<%= id %>">
+  <div class="page-header">
+    <h1>
+      <a href="#<%= id %>"><%= title %></a>
+    </h1>
   </div>
-    </div>
+  <%= content %>
-  </body>
+</div>
-</html>
+