Repository files navigation

This is a GitHub API resource built withnanoc.

All submissions are welcome. To submit a change, fork this repo, commit your changes, and send us apull request.

Ruby 1.9 is required to build the site.

Get the nanoc gem, plus kramdown for markdown parsing:

bundle install

You can see the available commands with nanoc:

nanoc -h

Nanoc hassome nice documentation to get you started. Though if you're mainly concerned with editing or adding content, you won't need to know much about nanoc.

Not sure how to structure the docs? Here's what the structure of theAPI docs should look like:

# API title## API endpoint title    [VERB] /path/to/endpoint.json### Parametersname: description### Input (request json body)<%= json :field => "sample value" %>### Response<%= headers 200, :pagination => true, 'X-Custom-Header' => "value" %><%= json :resource_name %>

Note: We're usingKramdown Markdown extensions, such as definition lists.

We specify the JSON responses in ruby so that we don't have to writethem by hand all over the docs. You can render the JSON for a resourcelike this:

<%= json :issue%>

This looks upGitHub::Resources::ISSUE inlib/resources.rb.

Some actions return arrays. You can modify the JSON by passing a block:

<%= json(:issue) { |hash| [hash] }%>

You can specify terminal blocks withpre.terminal elements. It'd benice if Markdown could do this more cleanly...

<pre>$ curl foobar....</pre>

This isn't acurl tutorial though, I'm not sure every API call needsto show how to access it withcurl.

Nanoc compiles the site into static files living in./output. It'ssmart enough not to try to compile unchanged files:

$ nanoc compileLoading 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.htmlSite compiled in 5.81s.

You can setup whatever you want to view the files. If you have the adsfgem, however (I hope so, it was in the Gemfile), you can start Webrick:

$ nanoc view$ open http://localhost:3000

Compilation times got you down? Useautocompile!

$ nanoc autocompile

This starts a web server too, so there's no need to runnanoc view.One thing: remember to add trailing slashes to all nanoc links!

$ rake publish

• Integrate through a simple hurl.it app for live API calls.
• Maybe add a nice TOC at the top of each page.
• Write a task for verifying JSON Resource examples against the actualAPI.