sorava · sorava · Aug 29, 2014 · Aug 29, 2014 · Aug 29, 2014 · Aug 29, 2014
diff --git a/.gitattributes b/.gitattributes
@@ -0,0 +1 @@
+*.svg eol=lf
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,10 @@
+output
+tmp
+.DS_Store
+.bundle
+bin
+crash.log
+/vendor/gems/
+/bin/
+/.bundle/
+static/search-index.json
diff --git a/.ruby-version b/.ruby-version
@@ -0,0 +1 @@
+1.9.3
diff --git a/.travis.yml b/.travis.yml
@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 1.9.3
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,7 @@
+Found a typo? Have an idea for improving the docs? Feel free to open a pull request and we'll get it merged as soon as we can!
+
+If you have a specific question or issues with the API, please [let us know](https://github.com/contact).
+
+## Do you work at GitHub?
+
+If you're a GitHub employee, please take a look at [our GitHubber article](https://githubber.com/article/crafts/writing/everything-you-need-to-know-about-the-Developer-blog) for more specific information on contributing.
diff --git a/Gemfile b/Gemfile
@@ -0,0 +1,24 @@
+source "http://rubygems.org"
+
+ruby '1.9.3'
+
+gem 'builder'
+gem 'coderay'
+gem 'kramdown', '~> 0.13.2'
+gem 'mime-types', '~> 1.16'
+gem 'nanoc', '~> 3.7'
+gem 'nokogiri', '~> 1.6.0'
+gem 'rouge', '~> 1.4'
+gem 'rake', '~> 0.9.2'
+gem 'thin'
+gem 'yajl-ruby', '~> 0.8.2'
+
+group :development do
+  gem 'adsf'
+  gem 'fssm'
+  gem 'guard-nanoc'
+end
+
+group :test do
+  gem 'html-proofer'
+end
diff --git a/Gemfile.lock b/Gemfile.lock
@@ -0,0 +1,88 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    adsf (1.2.0)
+      rack (>= 1.0.0)
+    builder (3.2.2)
+    celluloid (0.15.2)
+      timers (~> 1.1.0)
+    coderay (1.1.0)
+    colored (1.2)
+    cri (2.6.1)
+      colored (~> 1.2)
+    daemons (1.1.9)
+    ethon (0.7.0)
+      ffi (>= 1.3.0)
+    eventmachine (1.0.3)
+    ffi (1.9.3)
+    formatador (0.2.5)
+    fssm (0.2.10)
+    guard (2.6.1)
+      formatador (>= 0.2.4)
+      listen (~> 2.7)
+      lumberjack (~> 1.0)
+      pry (>= 0.9.12)
+      thor (>= 0.18.1)
+    guard-nanoc (1.0.2)
+      guard (>= 1.8.0)
+      nanoc (>= 3.6.3)
+    html-proofer (0.7.1)
+      colored (~> 1.2)
+      mercenary (~> 0.3.2)
+      nokogiri (~> 1.6.0)
+      typhoeus (~> 0.6.7)
+      yell (~> 2.0)
+    kramdown (0.13.8)
+    listen (2.7.9)
+      celluloid (>= 0.15.2)
+      rb-fsevent (>= 0.9.3)
+      rb-inotify (>= 0.9)
+    lumberjack (1.0.9)
+    mercenary (0.3.3)
+    method_source (0.8.2)
+    mime-types (1.25.1)
+    mini_portile (0.6.0)
+    nanoc (3.7.1)
+      cri (~> 2.3)
+    nokogiri (1.6.2.1)
+      mini_portile (= 0.6.0)
+    pry (0.10.0)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
+      slop (~> 3.4)
+    rack (1.5.2)
+    rake (0.9.6)
+    rb-fsevent (0.9.4)
+    rb-inotify (0.9.5)
+      ffi (>= 0.5.0)
+    rouge (1.4.0)
+    slop (3.6.0)
+    thin (1.6.2)
+      daemons (>= 1.0.9)
+      eventmachine (>= 1.0.0)
+      rack (>= 1.0.0)
+    thor (0.19.1)
+    timers (1.1.0)
+    typhoeus (0.6.8)
+      ethon (>= 0.7.0)
+    yajl-ruby (0.8.3)
+    yell (2.0.4)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  adsf
+  builder
+  coderay
+  fssm
+  guard-nanoc
+  html-proofer
+  kramdown (~> 0.13.2)
+  mime-types (~> 1.16)
+  nanoc (~> 3.7)
+  nokogiri (~> 1.6.0)
+  rake (~> 0.9.2)
+  rouge (~> 1.4)
+  thin
+  yajl-ruby (~> 0.8.2)
diff --git a/Guardfile b/Guardfile
@@ -0,0 +1,8 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard 'nanoc' do
+  watch('nanoc.yaml') # Change this to config.yaml if you use the old config file name
+  watch('Rules')
+  watch(%r{^(content|layouts|lib|static)/.*$})
+end
diff --git a/README.md b/README.md
@@ -0,0 +1,140 @@
+# developer.github.com
+
+This is a GitHub API resource built with [nanoc][nanoc].
+
+All submissions are welcome. To submit a change, fork this repo, commit your changes, and send us a [pull request](http://help.github.com/send-pull-requests/).
+
+## Setup
+
+Ruby 1.9 is required to build the site.
+
+Get the nanoc gem, plus kramdown for Markdown parsing:
+
+```sh
+$ bundle install
+```
+
+You can see the available commands with nanoc:
+
+```sh
+$ bundle exec nanoc -h
+```
+
+Nanoc has [some nice documentation](http://nanoc.ws/docs/tutorial/) to get you started.  Though if you're mainly concerned with editing or adding content, you won't need to know much about nanoc.
+
+[nanoc]: http://nanoc.ws/
+
+## Styleguide
+
+Not sure how to structure the docs?  Here's what the structure of the
+API docs should look like:
+
+    # API title
+
+    * TOC
+    {:toc}
+
+    ## API endpoint title
+
+        [VERB] /path/to/endpoint
+
+    ### Parameters
+
+    Name | Type | Description
+    -----|------|--------------
+    `name`|`type` | Description.
+
+    ### Input (request JSON body)
+
+    Name | Type | Description
+    -----|------|--------------
+    `name`|`type` | Description.
+
+    ### Response
+
+    <%= headers 200, :pagination => default_pagination_rels, 'X-Custom-Header' => "value" %>
+    <%= json :resource_name %>
+
+**Note**: We're using [Kramdown Markdown extensions](http://kramdown.gettalong.org/syntax.html), such as definition lists.
+
+### JSON Responses
+
+We specify the JSON responses in Ruby so that we don't have to write
+them by hand all over the docs.  You can render the JSON for a resource
+like this:
+
+```erb
+<%= json :issue %>
+```
+
+This looks up `GitHub::Resources::ISSUE` in `lib/resources.rb`.
+
+Some actions return arrays.  You can modify the JSON by passing a block:
+
+```erb
+<%= json(:issue) { |hash| [hash] } %>
+```
+
+### Terminal blocks
+
+You can specify terminal blocks with `pre.terminal` elements.  (It'd be nice if
+Markdown could do this more cleanly.)
+
+```html
+<pre class="terminal">
+$ curl foobar
+....
+</pre>
+```
+
+This is not a `curl` tutorial though. Not every API call needs
+to show how to access it with `curl`.
+
+## Development
+
+Nanoc compiles the site into static files living in `./output`.  It's
+smart enough not to try to compile unchanged files:
+
+```sh
+$ bundle exec nanoc compile
+Loading site data...
+Compiling site...
+   identical  [0.00s]  output/css/960.css
+   identical  [0.00s]  output/css/pygments.css
+   identical  [0.00s]  output/css/reset.css
+   identical  [0.00s]  output/css/styles.css
+   identical  [0.00s]  output/css/uv_active4d.css
+      update  [0.28s]  output/index.html
+      update  [1.31s]  output/v3/gists/comments/index.html
+      update  [1.92s]  output/v3/gists/index.html
+      update  [0.25s]  output/v3/issues/comments/index.html
+      update  [0.99s]  output/v3/issues/labels/index.html
+      update  [0.49s]  output/v3/issues/milestones/index.html
+      update  [0.50s]  output/v3/issues/index.html
+      update  [0.05s]  output/v3/index.html
+
+Site compiled in 5.81s.
+```
+
+You can setup whatever you want to view the files. If using the adsf
+gem (as listed in the Gemfile), you can start Webrick:
+
+```sh
+$ bundle exec nanoc view
+$ open http://localhost:3000
+```
+
+Compilation times got you down?  Use `autocompile`!
+
+```sh
+$ bundle exec nanoc autocompile
+```
+
+This starts a web server too, so there's no need to run `nanoc view`.
+One thing: remember to add trailing slashes to all nanoc links!
+
+## Deploy
+
+```sh
+$ bundle exec rake publish
+```
diff --git a/Rakefile b/Rakefile
@@ -0,0 +1,83 @@
+require 'nanoc3/tasks'
+require 'tmpdir'
+
+task :default => [:test]
+
+desc "Compile the site"
+task :compile do
+  `nanoc compile`
+end
+
+desc "Test the output"
+task :test => [:clean, :remove_output_dir, :compile] do
+  require 'html/proofer'
+  HTML::Proofer.new("./output").run
+end
+
+desc "Remove the output dir"
+task :remove_output_dir do
+  FileUtils.rm_r('output') if File.exist?('output')
+end
+
+# Prompt user for a commit message; default: P U B L I S H :emoji:
+def commit_message(no_commit_msg = false)
+  publish_emojis = [':boom:', ':rocket:', ':metal:', ':bulb:', ':zap:',
+    ':sailboat:', ':gift:', ':ship:', ':shipit:', ':sparkles:', ':rainbow:']
+  default_message = "P U B L I S H #{publish_emojis.sample}"
+
+  unless no_commit_msg
+    print "Enter a commit message (default: '#{default_message}'): "
+    STDOUT.flush
+    mesg = STDIN.gets.chomp.strip
+  end
+
+  mesg = default_message if mesg.nil? || mesg == ''
+  mesg.gsub(/'/, '') # Allow this to be handed off via -m '#{message}'
+end
+
+desc "Publish to http://developer.github.com"
+task :publish, [:no_commit_msg] => [:clean, :remove_output_dir] do |t, args|
+  mesg = commit_message(args[:no_commit_msg])
+  sh "nanoc compile"
+
+  # save precious files
+  if ENV['IS_HEROKU']
+    `git checkout origin/gh-pages`
+  else
+    `git checkout gh-pages`
+  end
+  tmpdir = Dir.mktmpdir
+  FileUtils.cp_r("enterprise", tmpdir)
+  FileUtils.cp("robots.txt", tmpdir)
+  `git checkout master`
+
+  ENV['GIT_DIR'] = File.expand_path(`git rev-parse --git-dir`.chomp)
+  ENV['RUBYOPT'] = nil
+  old_sha = `git rev-parse refs/remotes/origin/gh-pages`.chomp
+  Dir.chdir('output') do
+    ENV['GIT_INDEX_FILE'] = gif = '/tmp/dev.gh.i'
+    ENV['GIT_WORK_TREE'] = Dir.pwd
+    File.unlink(gif) if File.file?(gif)
+    # restore precious files
+    FileUtils.cp_r("#{tmpdir}/enterprise", ".")
+    FileUtils.cp("#{tmpdir}/robots.txt", ".")
+    FileUtils.rm_rf(tmpdir) if File.exists?(tmpdir)
+    `git add -A`
+    tsha = `git write-tree`.strip
+    puts "Created tree   #{tsha}"
+    # Heroku runs git@1.7, we don't have the luxury of -m
+    if ENV['IS_HEROKU']
+      `echo #{mesg} > changelog`
+      csha = `git commit-tree #{tsha} -p #{old_sha} < changelog`.strip
+    elsif old_sha.size == 40
+      csha = `git commit-tree #{tsha} -p #{old_sha} -m '#{mesg}'`.strip
+    else
+      csha = `git commit-tree #{tsha} -m '#{mesg}'`.strip
+    end
+    puts "Created commit #{csha}"
+    puts `git show #{csha} --stat`
+    puts "Updating gh-pages from #{old_sha}"
+    `git update-ref refs/heads/gh-pages #{csha}`
+    `git push origin gh-pages`
+  end
+end