Skip to content

Comparing changes

Choose two branches to see what’s changed or to start a new pull request. If you need to, you can also compare across forks.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also compare across forks.
...
  • 2 commits
  • 11 files changed
  • 0 commit comments
  • 1 contributor
View
2 .gitignore
@@ -12,3 +12,5 @@
# Ignore Sass' cache
/.sass-cache
+
+/tmp
View
11 Guardfile
@@ -0,0 +1,11 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard :shell do
+ watch %r{^lib/.+\.rb} do
+ puts "restarting server"
+ %x{pid=`ps ax | grep puma | head -1 | awk '{print $1}'`; kill -s USR2 $pid}
+ end
+end
+
+
View
23 README.mkd
@@ -0,0 +1,23 @@
+
+## Goals
+
+### Main docs in a single page
+
+[Parse API](https://www.parse.com/docs/rest)
+[Blog Post explaining why on Parse API](http://blog.parse.com/2012/01/11/designing-great-api-docs/)
+
+Separate pages ok for long-form parts, like detailed multi-step tutorials, OAuth, etc...
+
+### Inline code examples for each language/library we "support"
+
+[Stripe's API Docs](https://stripe.com/docs/api) has a switcher at top to pick your preferred language.
+
+### Use the user's token in examples
+
+If the visitor is logged in to github.com, automatically use their username/token in the examples. We'll probably have
+to punt on several of the examples, though. Eg, `/user` would show the current user, but we don't want to have to remake
+the request for each example * language on the page. This would lead nicely into a future javascript API explorer, though.
+
+
+
+
View
2 config.rb
@@ -39,3 +39,5 @@
activate Doctaur
ignore "templates/*"
+ignore "**/*.doctaur"
+
View
4 config.ru
@@ -0,0 +1,4 @@
+require 'rubygems'
+require 'middleman'
+
+run Middleman.server
View
7 lib/doc_helpers.rb
@@ -28,7 +28,7 @@ def pages_for_quick_ref
next if category.nil? # Skip pages that don't have "category" metadata
next if category == "summary" # Skip the summary pages in the quick reference
next if category == "."
- pages_for_quick_ref[category] = sort_pages(pages).select { |p| p.path !~ /index/ && p.path !~ /representation/ }
+ pages_for_quick_ref[category] = sort_pages(pages).select { |p| p.is_a? Doctaur::ApiResource }
end
pages_for_quick_ref
@@ -61,7 +61,7 @@ def sort_pages(pages)
category = filepath.split(File::Separator).last
# First, order by category
- res = [ category,
+ [ category,
if filename =~ /index/
# Index always comes first
-10
@@ -87,9 +87,6 @@ def sort_pages(pages)
end
]
- p res
- res
-
end
end
View
39 lib/doctaur.rb
@@ -8,8 +8,8 @@ def registered(app)
end
app.after_configuration do
- sitemap.register_resource_list_manipulator(:representations,
- Doctaur::RepresentationManipulator.new(self),
+ sitemap.register_resource_list_manipulator(:doctaur,
+ Doctaur::Manipulator.new(self),
false)
end
@@ -37,12 +37,12 @@ module Helpers
def represent(name, options = {}, &block)
representation = Doctaur::Representation.new(name, options, &block)
- render_individual_file "/templates/representation.html.haml", representation.locals
+ partial "templates/representation", locals: {representation: representation}
end
end
- class RepresentationManipulator
+ class Manipulator
def initialize(app)
@app = app
@@ -50,16 +50,23 @@ def initialize(app)
def manipulate_resource_list(resources)
resources.each do |resource|
+ next unless resource.mime_type =~ /text\/html/
+
resource.extend PageExtensions
if resource.source_file =~ /doctaur$/
- resource.extend RepresentationResource
+ if resource.source_file =~ /representation/
+ resource.extend RepresentationResource
+ else
+ resource.extend ApiResource
+ end
end
category = File.split(resource.path).first.split(File::Separator).last
resource.add_metadata(page: {category: category}) if category
end
end
+
end
module PageExtensions
@@ -67,14 +74,14 @@ def title
data["title"]
end
- def anchor
- data["title"].underscore
- end
-
def category
# foo/bar/baz.html.mkd #-> "bar"
data["category"] || File.split(path).first.split(File::Separator).last
end
+
+ def anchor
+ title.underscore if title
+ end
end
module RepresentationResource
@@ -87,6 +94,18 @@ def anchor
"#{category}_representation"
end
+ def render(options = {}, locals = {}, &block)
+
+ end
+
+ end
+
+ module ApiResource
+
+ def endpoint
+
+ end
+
end
class Representation
@@ -133,7 +152,7 @@ def locals
:attributes => attributes,
:links => links,
:example => example,
- :anchor => anchor
+ :anchor => "#{name}_representation"
}
end
View
8 source/summary/quick_ref.html.haml
@@ -4,6 +4,7 @@ sort_order: 2
---
%h1 Quick Reference
+- p "Rendering Quick Reference"
- pages_for_quick_ref.each do |category, pages|
@@ -19,12 +20,13 @@ sort_order: 2
%tbody
- pages.each do |page|
+ - p page.path
%tr
%td.usage
- = link_to page.data["title"], "##{page.data["title"].underscore.gsub(' ', '_')}"
+ = link_to page.title, page.anchor
%td.method
- = page.data["method"] || page.data["methods"].join(', ')
+ = page.methods
%td.url
- = page.data["endpoint"]
+ = page.endpoint
View
2 source/templates/representation.html.haml
@@ -1,4 +1,4 @@
-%h2{id: anchor} Representation
+%h2{anchor: anchor} Representation
%h3 Attributes
%dl.attributes
View
27 source/user/current_user.html.doctaur
@@ -0,0 +1,27 @@
+
+api :get, "/user" do
+
+ title "Retrieve current user"
+ representation :user, :v3
+
+ requires :authentiction
+
+ desc <<-DESC
+ Retrives public data for the currently logged in user.
+ DESC
+
+ example :curl, <<-EX
+ curl -H "Authentication: token {{token}}" https://api.github.com/user
+ EX
+
+ example :ruby, <<-EX
+ @github.current_user
+ EX
+
+
+
+
+
+end
+
+# vim: ft=ruby
View
49 source/user/current_user.html.markdown
@@ -1,49 +0,0 @@
----
-title: Current user
-endpoint: /user
-method: GET
-category: users
----
-
-# Retrieve the currently logged in user
-
-Retrieves all public data for the currently logged in user
-
-<p class="alert">Requires authentication</p>
-
- GET /user
-
-## Example
-
-### Terminal
-
- $ http https://api.github.com/user
-
- {
- "avatar_url": "https://secure.gravatar.com/avatar/d587890d0fcf8f45724baa8b1bfe1bf4?d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-140.png",
- "bio": "",
- "blog": "blog.theamazingrando.com",
- "company": "GitHub",
- "created_at": "2008-02-11T18:44:09Z",
- "email": "psadauskas@gmail.com",
- "followers": 35,
- "following": 1,
- "gravatar_id": "d587890d0fcf8f45724baa8b1bfe1bf4",
- "hireable": false,
- "html_url": "https://github.com/paul",
- "id": 184,
- "location": "Boulder, CO",
- "login": "paul",
- "name": "Paul Sadauskas",
- "public_gists": 323,
- "public_repos": 83,
- "type": "User",
- "url": "https://api.github.com/users/paul"
- }
-
-### Ruby
-
- @github = Github::Client.new("https://api.github.com")
- @github.current_user
- # => #<User login: "paul">
-

No commit comments for this range

Something went wrong with that request. Please try again.