Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Own sitemap loader thing

  • Loading branch information...
commit d15a94176272c2078fe31fd2e348d94121943dd6 1 parent 4bfe0c8
@paul authored
View
1  Gemfile
@@ -2,6 +2,7 @@ source :rubygems
gem "middleman", "~>3.0.0"
gem "activesupport", "~>3.2.0"
+gem "github-markdown"
gem "awesome_print", :require => "ap"
gem "prissy"
View
2  Gemfile.lock
@@ -19,6 +19,7 @@ GEM
fattr (2.2.1)
ffi (1.1.0)
fssm (0.2.9)
+ github-markdown (0.5.0)
haml (3.1.6)
hike (1.2.1)
http_router (0.10.2)
@@ -116,5 +117,6 @@ PLATFORMS
DEPENDENCIES
activesupport (~> 3.2.0)
awesome_print
+ github-markdown
middleman (~> 3.0.0)
prissy
View
48 config.rb
@@ -1,51 +1,5 @@
-###
-# Compass
-###
-# Susy grids in Compass
-# First: gem install compass-susy-plugin
-# require 'susy'
-
-# Change Compass configuration
-# compass_config do |config|
-# config.output_style = :compact
-# end
-
-###
-# Page options, layouts, aliases and proxies
-###
-
-# Per-page layout changes:
-#
-# With no layout
-# page "/path/to/file.html", :layout => false
-#
-# With alternative layout
-# page "/path/to/file.html", :layout => :otherlayout
-#
-# A path which all have the same layout
-# with_layout :admin do
-# page "/admin/*"
-# end
-
-# Proxy (fake) files
-# page "/this-page-has-no-template.html", :proxy => "/template-file.html" do
-# @which_fake_page = "Rendering a fake page with a variable"
-# end
-
-###
-# Helpers
-###
-
-# Automatic image dimensions on image_tag helper
-# activate :automatic_image_sizes
-
-# Methods defined in the helpers block are available in templates
-# helpers do
-# def some_helper
-# "Helping"
-# end
-# end
+set :markdown_engine, :github_markup
set :css_dir, 'stylesheets'
View
53 lib/doc_helpers.rb
@@ -10,11 +10,11 @@ def all_pages
end
end
- def pages_by_category
-
+ def pages_for_toc
pages_by_category = {}
- sitemap.resources.group_by { |page| page.data["category"] }.each do |category, pages|
+ group_by_sorted_category(all_pages).each do |category, pages|
next if category.nil? # Skip pages that don't have "category" metadata
+ next if category == "."
pages_by_category[category] = sort_pages(pages).select { |p| p.path !~ /index/ }
end
@@ -24,9 +24,10 @@ def pages_by_category
def pages_for_quick_ref
pages_for_quick_ref = {}
- sitemap.resources.group_by { |page| page.data["category"] }.each do |category, pages|
+ group_by_sorted_category(all_pages).each do |category, pages|
next if category.nil? # Skip pages that don't have "category" metadata
- next if category == "summary"
+ 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/ }
end
@@ -36,15 +37,36 @@ def pages_for_quick_ref
HTTP_METHOD_SORT_ORDER = %w[GET POST PUT PATCH DELETE]
+ def group_by_sorted_category(pages)
+ pages_by_category = {}
+
+ pages.each do |page|
+ category = page_category(page)
+ next if category.nil?
+ pages_by_category[category] ||= []
+ pages_by_category[category] << page
+ end
+
+ sorted = pages_by_category.sort_by do |key, value|
+ key..to_s == "summary" ? -1 : key
+ end
+
+ Hash[sorted]
+ end
+
def sort_pages(pages)
pages.sort_by do |page|
- [ page.data["category"],
- if page.path =~ /index/
+ filepath, filename = File.split(page.path)
+ category = filepath.split(File::Separator).last
+
+ # First, order by category
+ res = [ category,
+ if filename =~ /index/
# Index always comes first
-10
- elsif page.path =~ /representation/
+ elsif filename =~ /representation/
# Representation comes next
-5
@@ -52,16 +74,27 @@ def sort_pages(pages)
# If the page metadata specifies a sort order, do that
page.data["sort_order"]
- else
- # Otherwise, guess by url length and http method
+ elsif page.data["endpoint"]
+ # url length and http method
endpoint = page.data["endpoint"].length
method = HTTP_METHOD_SORT_ORDER.index(page.data["method"] || page.data["methods"].first)
endpoint * 10 + method
+
+ else
+ # Otherwise, alphabetic by filename
+ filename.to_i
end
]
+ p res
+ res
+
end
end
+
+ def page_category(page)
+ File.split(page.path).first.split(File::Separator).last
+ end
end
View
56 lib/doctaur.rb
@@ -7,6 +7,12 @@ def registered(app)
template_extensions :doctaur => :html
end
+ app.after_configuration do
+ sitemap.register_resource_list_manipulator(:representations,
+ Doctaur::RepresentationManipulator.new(self),
+ false)
+ end
+
app.helpers Doctaur::Helpers
end
alias included registered
@@ -36,6 +42,53 @@ def represent(name, options = {}, &block)
end
+ class RepresentationManipulator
+
+ def initialize(app)
+ @app = app
+ end
+
+ def manipulate_resource_list(resources)
+ resources.each do |resource|
+ resource.extend PageExtensions
+
+ if resource.source_file =~ /doctaur$/
+ resource.extend RepresentationResource
+ end
+
+ category = File.split(resource.path).first.split(File::Separator).last
+ resource.add_metadata(page: {category: category}) if category
+ end
+ end
+ end
+
+ module PageExtensions
+ 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
+ end
+
+ module RepresentationResource
+
+ def title
+ "Representation"
+ end
+
+ def anchor
+ "#{category}_representation"
+ end
+
+ end
+
class Representation
attr_reader :name
@@ -79,7 +132,8 @@ def locals
:name => name,
:attributes => attributes,
:links => links,
- :example => example
+ :example => example,
+ :anchor => anchor
}
end
View
4 source/_toc.html.haml
@@ -2,7 +2,7 @@
%h1 Table of Contents
%ul.categories
- - pages_by_category.each do |category, pages|
+ - pages_for_toc.each do |category, pages|
%li.category
= link_to category.titlecase, "##{category}"
@@ -10,4 +10,4 @@
%ul.pages
- pages.each do |page|
%li.page
- = link_to page.data["title"], "##{page.data["title"].underscore.gsub(' ', '_')}"
+ = link_to page.title, "##{page.anchor}"
View
7 source/index.html.haml
@@ -5,3 +5,10 @@ category: summary
%h1 GitHub API
+This describes the resources that make up the official GitHub API v3. If
+you have any problems or requests please contact
+[support](mailto:support@github.com?subject=APIv3).
+
+View the [API Changelog](/v3/changelog) for information on existing and
+planned changes to the API.
+
View
120 source/summary/libraries.mkd
@@ -0,0 +1,120 @@
+---
+ sort_order: 5
+ title: Libraries
+---
+
+# Libraries
+
+Libraries for accessing the GitHub API from your favorite language.
+
+## ActionScript
+
+* [ActionScript GitHub API][as3]
+
+[as3]: https://github.com/cbrammer/api-github-as3
+
+## Clojure
+
+* [Tentacles][tentacles]
+
+[tentacles]: https://github.com/Raynes/tentacles
+
+## CSharp
+
+* [CSharp GitHub API][csharp]
+
+[csharp]: https://github.com/sgrassie/csharp-github-api
+
+## Erlang
+
+* [Erlang GitHub API][erlang]
+
+[erlang]: https://github.com/onlyshk/erlang-github-api
+
+## Haskell
+
+* [Haskell GitHub API][haskell]
+
+[haskell]: https://github.com/dmnpignaud/haskell-github-api
+
+## Java
+
+The [GitHub Java API](https://github.com/eclipse/egit-github/tree/master/org.eclipse.egit.github.core) library
+is part of the [GitHub Mylyn Connector](https://github.com/eclipse/egit-github) and aims to support the entire
+GitHub v3 API. Builds are available in [Maven Central](http://search.maven.org/#search%7Cga%7C1%7Ca%3A%22org.eclipse.egit.github.core%22).
+
+## Javascript
+
+* [Node-GitHub][ajaxorg-node-github]
+* [NodeJS GitHub library][octonode]
+* [gh3 client-side API v3 wrapper][gh3]
+
+[ajaxorg-node-github]: https://github.com/ajaxorg/node-github
+[octonode]: https://github.com/pksunkara/octonode
+[gh3]: https://github.com/k33g/gh3
+
+## Objective-C
+
+* [UAGithubEngine][uagithubengine]
+
+[uagithubengine]: http://github.com/owainhunt/uagithubengine
+
+## Perl
+
+* [Pithub][pithub-github] ([CPAN][pithub-cpan])
+* [Net::Github][net-github-github] ([CPAN][net-github-cpan])
+
+[net-github-github]: https://github.com/fayland/perl-net-github
+[net-github-cpan]: http://search.cpan.org/~fayland/Net-GitHub-0.30/lib/Net/GitHub.pm
+[pithub-github]: https://github.com/plu/Pithub
+[pithub-cpan]: http://metacpan.org/module/Pithub
+
+## PHP
+
+* [GitHub API][github-api]
+* [PHP GitHub API][php-github-api]
+* [GitHub Kohana Module][kohana]
+
+[github-api]: https://github.com/yiiext/github-api
+[php-github-api]: https://github.com/ornicar/php-github-api
+[kohana]: https://github.com/acoulton/github_v3_api
+
+## Python
+
+* [PyGithub][jacquev6_pygithub]
+* [Pygithub3][pygithub3-api]
+* [libsaas][libsaas]
+* [github3.py][github3py]
+* [sanction][sanction]
+* [agithub][agithub]
+
+[jacquev6_pygithub]: https://github.com/jacquev6/PyGithub
+[pygithub3-api]: https://github.com/copitux/python-github3
+[libsaas]: https://github.com/ducksboard/libsaas
+[github3py]: https://github.com/sigmavirus24/github3.py
+[sanction]: https://github.com/demianbrecht/sanction
+[agithub]: https://github.com/jpaugh64/agithub "Agnostic Github"
+
+## Ruby
+
+* [Octokit][octokit]
+* [GitHub API Gem][ghapi]
+* [Octocat Herder][herder]
+* [GitHub v3 API][ruby1]
+* [GitHub API Client][ruby2]
+* [Ghee][ghee]
+
+[octokit]: https://github.com/pengwynn/octokit
+[herder]: https://github.com/jhelwig/octocat_herder
+[ghapi]: https://github.com/peter-murach/github
+[ruby1]: https://github.com/jwilger/github-v3-api
+[ruby2]: https://github.com/okonski/github-api-client
+[ghee]: https://github.com/rauhryan/ghee
+
+## Scala
+
+* [Dispatch GitHub][scala]
+
+[scala]: https://github.com/andreazevedo/dispatch-github
+
+
View
14 source/summary/mime_type.html.mkd
@@ -0,0 +1,14 @@
+---
+ sort_order: 1
+ title: Mime Type
+---
+
+# Mime Type
+
+The GitHub API uses a vendor-specific mime type for web service requests and responses.
+
+ application/vnd.github.v3+json
+
+We also accept the common `application/json` as an alias, but strongly discourage its use. It will always be mapped to the latest version of the API. If we upgrade the API at some point in the future, and you are relying on the previous version, bad things will probably happen.
+
+
View
264 source/summary/oauth.mkd
@@ -0,0 +1,264 @@
+---
+ sort_order: 3
+ title: OAuth
+---
+
+# OAuth
+
+OAuth2 is a protocol that lets external apps request authorization to
+private details in a user's GitHub account without getting their
+password. This is preferred over Basic Authentication because tokens can
+be limited to specific types of data, and can be revoked by users at any
+time.
+
+All developers need to [register their
+application](https://github.com/settings/applications/new) before getting
+started. A registered OAuth application is assigned a unique Client ID
+and Client Secret. The Client Secret should not be shared.
+
+## Web Application Flow
+
+This is a description of the OAuth flow from 3rd party web sites.
+
+### 1. Redirect users to request GitHub access
+
+ GET https://github.com/login/oauth/authorize
+
+### Parameters
+
+client\_id
+: _Required_ **string** - The client ID you received from GitHub when
+you [registered](https://github.com/settings/applications/new).
+
+redirect\_uri
+: _Optional_ **string** - URL in your app where users will be sent
+after authorization. See details below about [redirect
+urls](#redirect-urls).
+
+scope
+: _Optional_ **string** - Comma separated list of [scopes](#scopes).
+
+state
+: _Optional_ **string** - An unguessable random string. It is used to protect
+against cross-site request forgery attacks.
+
+### 2. GitHub redirects back to your site
+
+If the user accepts your request, GitHub redirects back to your site
+with a temporary code in a code parameter as well as the state you provided in
+the previous step in a state parameter. If the states don't match, the request
+has been created by a third party and the process should be aborted.
+
+Exchange this for an access token:
+
+ POST https://github.com/login/oauth/access_token
+
+### Parameters
+
+client\_id
+: _Required_ **string** - The client ID you received from GitHub when
+you [registered](https://github.com/settings/applications/new).
+
+redirect\_uri
+: _Optional_ **string**
+
+client\_secret
+: _Required_ **string** - The client secret you received from GitHub
+when you [registered](https://github.com/settings/applications/new).
+
+code
+: _Required_ **string** - The code you received as a response to [Step 1](#redirect-users-to-request-github-access).
+
+state
+: _Required_ **string** - The state value you provided in Step 1.
+
+### Response
+
+By default, the response will take the following form:
+
+ access_token=e72e16c7e42f292c6912e7710c838347ae178b4a&token_type=bearer
+
+You can also receive the content in different formats depending on the Accept
+header:
+
+ Accept: application/json
+ {"access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a","token_type":"bearer"}
+
+ Accept: application/xml
+ <OAuth>
+ <token_type>bearer</token_type>
+ <access_token>e72e16c7e42f292c6912e7710c838347ae178b4a</access_token>
+ </OAuth>
+
+### 3. Use the access token to access the API
+
+The access token allows you to make requests to the API on a behalf of a user.
+
+ GET https://api.github.com/user?access_token=...
+
+## Non-Web Application Flow
+
+Use basic authentication to create an OAuth2 token using the [interface
+below](/v3/oauth#create-a-new-authorization). With this technique, a username
+and password need not be stored permanently, and the user can revoke access at
+any time.
+
+## Redirect URLs
+
+The `redirect_uri` parameter is optional. If left out, GitHub will
+redirect users to the callback URL configured in the OAuth Application
+settings. If provided, the redirect URL must match the callback URL's
+host.
+
+ CALLBACK: http://foo.com
+
+ GOOD: https://foo.com
+ GOOD: http://foo.com/bar
+ BAD: http://foo.com:8080
+ BAD: http://oauth.foo.com:8080
+ BAD: http://bar.com
+
+## Scopes
+
+Scopes let you specify exactly what type of access you need. This will
+be displayed to the user on the authorize form.
+
+Check headers to see what OAuth scopes you have, and what the API action
+accept.
+
+ $ curl -H "Authorization: bearer TOKEN" https://api.github.com/users/technoweenie -I
+ HTTP/1.1 200 OK
+ X-OAuth-Scopes: repo, user
+ X-Accepted-OAuth-Scopes: user
+
+`X-OAuth-Scopes` lists the scopes your token has authorized.
+`X-Accepted-OAuth-Scopes` lists the scopes that the action checks for.
+
+(no scope)
+: public read-only access (includes public user profile info, public
+repo info, and gists).
+
+user
+: Read/write access to profile info only.
+
+public\_repo
+: Read/write access to public repos and organizations.
+
+repo
+: Read/write access to public and private repos and organizations.
+
+delete\_repo
+: Delete access to adminable repositories.
+
+gist
+: write access to gists.
+
+NOTE: Your application can request the scopes in the initial redirection. You
+can specify multiple scopes by separating them by a comma.
+
+ https://github.com/login/oauth/authorize?
+ client_id=...&
+ scope=user,public_repo
+
+## OAuth Authorizations API
+
+There is an API for users to manage their own tokens. You can only
+access your own tokens, and only through Basic Authentication.
+
+## List your authorizations
+
+ GET /authorizations
+
+### Response
+
+<%= headers 200, :pagination => true %>
+<%= json(:oauth_access) { |h| [h] } %>
+
+## Get a single authorization
+
+ GET /authorizations/:id
+
+### Response
+
+<%= headers 200 %>
+<%= json :oauth_access %>
+
+## Create a new authorization
+
+Note: Authorizations created from the API will show up in the GitHub API
+app.
+
+ POST /authorizations
+
+### Input
+
+scopes
+: _Optional_ **array** - A list of scopes that this authorization is in.
+
+note
+: _Optional_ **string** - A note to remind you what the OAuth token is for.
+
+note_url
+: _Optional_ **string** - A URL to remind you what app the OAuth token is for.
+
+<%= json :scopes => ["public_repo"], :note => 'admin script' %>
+
+### Response
+
+<%= headers 201, :Location => "https://api.github.com/authorizations/1"
+%>
+<%= json :oauth_access %>
+
+## Update an existing authorization
+
+ PATCH /authorizations/:id
+
+### Input
+
+scopes
+: _Optional_ **array** - Replaces the authorization scopes with these.
+
+add_scopes
+: _Optional_ **array** - A list of scopes to add to this authorization.
+
+remove_scopes
+: _Optional_ **array** - A list of scopes to remove from this
+authorization.
+
+note
+: _Optional_ **string** - A note to remind you what the OAuth token is for.
+
+note_url
+: _Optional_ **string** - A URL to remind you what app the OAuth token is for.
+
+You can only send one of these scope keys at a time.
+
+<%= json :add_scopes => ['repo'], :note => 'admin script' %>
+
+### Response
+
+<%= headers 200 %>
+<%= json :oauth_access %>
+
+## Delete an authorization
+
+ DELETE /authorizations/:id
+
+### Response
+
+<%= headers 204 %>
+
+## More Information
+
+It can be a little tricky to get started with OAuth. Here are a few
+links that might be of help:
+
+* [OAuth 2 spec](http://tools.ietf.org/html/draft-ietf-oauth-v2-07)
+* [Facebook API](http://developers.facebook.com/docs/authentication/)
+* [Ruby OAuth2 lib](https://github.com/intridea/oauth2)
+* [simple ruby/sinatra example](https://gist.github.com/9fd1a6199da0465ec87c)
+* [simple python example](https://gist.github.com/e3fbd47fbb7ee3c626bb) using [python-oauth2](http://github.com/dgouldin/python-oauth2)
+* [Ruby OmniAuth example](http://github.com/intridea/omniauth)
+* [Ruby Sinatra extension](http://github.com/atmos/sinatra_auth_github)
+* [Ruby Warden strategy](http://github.com/atmos/warden-github)
+
View
1  source/summary/quick_ref.html.haml
@@ -1,7 +1,6 @@
---
title: Quick Reference
sort_order: 2
-category: summary
---
%h1 Quick Reference
View
2  source/templates/representation.html.haml
@@ -1,4 +1,4 @@
-%h2 Representation
+%h2{id: anchor} Representation
%h3 Attributes
%dl.attributes
View
0  source/users/by_login.html.markdown → source/user/by_login.html.markdown
File renamed without changes
View
0  source/users/current_user.html.markdown → source/user/current_user.html.markdown
File renamed without changes
View
5 source/users/index.html.mkd → source/user/index.html.mkd
@@ -1,8 +1,3 @@
----
-title: User
-category: users
----
-
# User
A **User** represents a person or automated actor on GitHub. They may own and
View
4 source/users/representation.html.doctaur → source/user/representation.html.doctaur
@@ -1,7 +1,3 @@
----
-category: users
-title: "Representation"
----
represent :user, with: :githubv3 do
View
0  source/users/update_current_user.html.markdown → source/user/update_current_user.html.markdown
File renamed without changes
Please sign in to comment.
Something went wrong with that request. Please try again.