From 72dae6867c68c189882aaec51a180503f276fcbd Mon Sep 17 00:00:00 2001
From: Konstantin Haase <konstantin.mailinglists@googlemail.com>
Date: Thu, 20 Sep 2012 14:15:30 +0200
Subject: [PATCH] start working on general docs
---
docs/00_overview.md | 7 ++
docs/01_cross_origin.md | 23 +++++
lib/travis/api/app/endpoint/documentation.rb | 95 +++++++++++++++-----
3 files changed, 102 insertions(+), 23 deletions(-)
create mode 100644 docs/00_overview.md
create mode 100644 docs/01_cross_origin.md
diff --git a/docs/00_overview.md b/docs/00_overview.md
new file mode 100644
index 00000000..f05ab353
--- /dev/null
+++ b/docs/00_overview.md
@@ -0,0 +1,7 @@
+# Overview
+
+... some general docs here ...
+
+## Media Types
+
+The API is currently JSON only.
\ No newline at end of file
diff --git a/docs/01_cross_origin.md b/docs/01_cross_origin.md
new file mode 100644
index 00000000..031f7209
--- /dev/null
+++ b/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 ...
diff --git a/lib/travis/api/app/endpoint/documentation.rb b/lib/travis/api/app/endpoint/documentation.rb
index e38262d1..5f56edac 100644
--- a/lib/travis/api/app/endpoint/documentation.rb
+++ b/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,29 +198,15 @@ __END__
<section class="span9">
+ <% general_docs.each do |doc| %>
+ <%= erb :entry, locals: doc %>
+ <% end %>
+
<% endpoints.each do |endpoint| %>
- <div id="<%= endpoint['name'] %>">
- <div class="page-header">
- <h1>
- <a href="#<%= endpoint['name'] %>"><%= endpoint['name'] %></a>
- </h1>
- </div>
- <% unless endpoint['doc'].to_s.empty? %>
- <%= docs_for endpoint %>
- <hr>
- <% end %>
- <% endpoint['routes'].each do |route| %>
- <div class="route" id="<%= slug_for(route) %>">
- <pre><h3><%= route['verb'] %> <%= route['uri'] %></h3></pre>
- <% if route['scope'] %>
- <p>
- <h5>Required autorization scope: <span class="label"><%= route['scope'] %></span></h5>
- </p>
- <% end %>
- <%= docs_for route %>
- </div>
- <% end %>
- </div>
+ <%= erb :entry, {},
+ id: endpoint['name'],
+ title: endpoint['name'],
+ content: erb(:endpoint_content, {}, endpoint: endpoint) %>
<% end %>
</section>
@@ -193,3 +214,31 @@ __END__
</div>
</body>
</html>
+
+@@ endpoint_content
+<% unless endpoint['doc'].to_s.empty? %>
+ <%= docs_for endpoint %>
+ <hr>
+<% end %>
+<% endpoint['routes'].each do |route| %>
+ <div class="route" id="<%= slug_for(route) %>">
+ <pre><h3><%= route['verb'] %> <%= route['uri'] %></h3></pre>
+ <% if route['scope'] %>
+ <p>
+ <h5>Required autorization scope: <span class="label"><%= route['scope'] %></span></h5>
+ </p>
+ <% end %>
+ <%= docs_for route %>
+ </div>
+<% end %>
+
+@@ entry
+<div id="<%= id %>">
+ <div class="page-header">
+ <h1>
+ <a href="#<%= id %>"><%= title %></a>
+ </h1>
+ </div>
+ <%= content %>
+</div>
+