GitHub Developer site
Ruby HTML CSS JavaScript Shell
Permalink
Failed to load latest commit information.
assets Sync changes from upstream repository Jun 27, 2016
content Sync changes from upstream repository Aug 23, 2016
data/variables Sync changes from upstream repository Feb 16, 2016
layouts Sync changes from upstream repository Aug 15, 2016
lib Sync changes from upstream repository Aug 15, 2016
script Revert "Sync changes from upstream repository" Aug 3, 2016
spec Sync changes from upstream repository Jun 27, 2016
tasks Revert "Sync changes from upstream repository" Aug 3, 2016
vendor/cache Sync changes from upstream repository Mar 7, 2016
.bowerrc Sync changes from upstream repository Nov 17, 2015
.gitattributes Move static resources around, adding new datasource to handle them Aug 6, 2011
.gitignore Revert "Sync changes from upstream repository" Aug 3, 2016
.ruby-version Sync changes from upstream repository Dec 5, 2015
.travis.yml Cache the npm modules as well Dec 22, 2015
Brewfile Sync changes from upstream repository Feb 26, 2016
CNAME developers developers developers developers developers developers dev… Apr 28, 2011
CONTRIBUTING.md Sync changes from upstream repository Jun 2, 2016
Gemfile Sync changes from upstream repository Mar 5, 2016
Gemfile.lock Sync changes from upstream repository Mar 7, 2016
Guardfile Sync changes from upstream repository Nov 7, 2014
LICENSE.txt Sync changes from upstream repository Dec 16, 2015
README.md Sync changes from upstream repository Jul 14, 2016
Rakefile Revert "Sync changes from upstream repository" Aug 3, 2016
Rules Sync changes from upstream repository Mar 11, 2016
bower.json Sync changes from upstream repository Dec 7, 2015
config.ru Merge from upstream Nov 18, 2015
gulpfile.js Sync changes from upstream repository Dec 22, 2015
nanoc.yaml Sync changes from upstream repository Aug 3, 2016
package.json Sync changes from upstream repository Jan 5, 2016
repository-sync Sync changes from upstream repository Aug 3, 2016

README.md

developer.github.com Build Status

This is a GitHub API resource built with Nanoc.

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

Development

You can fetch the latest dependencies by opening the command line and running script/bootstrap:

$ script/bootstrap
==> Installing gem dependencies…
==> Installing npm dependencies…

You'll need Ruby and Node installed on your system. The required versions for each of these languages can be found in the .ruby-version and package.json files, respectively.

You can run bundle exec rake build to generate the site, but it's often more useful to simply build the server and start the site at the same time.

Nanoc compiles the site into static files living in output. It's smart enough not to try to compile unchanged files.

You can start the site with script/server:

$ script/server
Loading site data...
Compiling site...
   create     [0.28s]  output/index.html
   create     [1.31s]  output/v3/gists/comments/index.html
   identical  [1.92s]  output/v3/gists/index.html
   identical  [0.25s]  output/v3/issues/comments/index.html
   update     [0.99s]  output/v3/issues/labels/index.html
   update     [0.05s]  output/v3/index.html
   …

Site compiled in 5.81s.

The site is hosted at http://localhost:4000.

Nanoc has some 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.

Enterprise

To generate the /enterprise versions, pass in the Enterprise version to script/server. For example:

$ script/server 2.6

Note that live reloading is not available for Enterprise documentation.

Styleguide

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

# API title

{: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, 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:

<%= 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:

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

There is also a rake task for generating JSON files from the sample responses in the documentation:

$ rake generate_json_from_responses

The generated files will end up in json-dump/.

Terminal blocks

You can specify terminal blocks by using the command-line syntax highlighting.

``` command-line
$ curl foobar
```

You can use certain characters, like $ and #, to emphasize different parts of commands.

``` command-line
# call foobar
$ curl <em>foobar<em>
....
```

For more information, see the reference documentation.

Deploy

Deployments happen automatically once a PR is merged into master. A tool called Publisher takes the master branch, builds it using Nanoc, and publishes the content to gh-pages. Thus, any commit to master is automatically sent over to gh-pages, where it's picked up and served by GitHub Pages.

Licenses

The code to generate the site (everything excluding the assets, content, and layouts directories) as well as the code samples on the site are licensed under CC0-1.0. CC0 waives all copyright restrictions but does not grant you any trademark permissions.

Site content (everything in the assets, content, and layouts directories, excluding files under open source licenses individually marked) is licensed under CC-BY-4.0. CC-BY-4.0 gives you permission to use content for almost any purpose but does not grant you any trademark permissions, so long as you note the license and give credit, such as follows:

Content based on developer.github.com used under the CC-BY-4.0 license.

This means you can use the code and content in this repository except for GitHub trademarks in your own projects.

When you contribute to this repository you are doing so under the above licenses.