docs: move documentation from README.md to documentation website

docs/gatsby-node.js

@@ -43,30 +43,3 @@ exports.onCreateNode = ({ node, getNode, actions }) => {
     })
   }
 }
-
-// exports.createPages = async ({ graphql, actions }) => {
-//   const { createPage } = actions
-
-//   const guidesPagesResult = await graphql(`{
-//     allMarkdownRemark {
-//       edges {
-//         node {
-//           fields {
-//             slug
-//           }
-//         }
-//       }
-//     }
-//   }`)
-//   guidesPagesResult.data.allMarkdownRemark.edges.forEach(({ node }) => {
-//     createPage({
-//       path: node.fields.slug,
-//       component: path.resolve(`./src/templates/guide.js`),
-//       context: {
-//         // Data passed to context is available
-//         // in page queries as GraphQL variables.
-//         slug: node.fields.slug
-//       }
-//     })
-//   })
-// }

docs/src/components/api-sub-menu.js

@@ -1,6 +1,8 @@
 import React, { Component } from "react"
 import apiStyles from './api.module.css'
 
+import upperFirst from 'lodash/upperFirst'
+
 export default class ApiSubMenu extends Component {
   constructor(props) {
     super(props)
@@ -18,7 +20,6 @@ export default class ApiSubMenu extends Component {
   }
 
   getPrimaryLinkClassName() {
-    // console.log(`ApiSubMenu.getPrimaryLinkClassName / this.props.activeMenuItem: ${this.props.activeMenuItem} / this.props.node.id: ${this.props.node.id}`)
     return [
       this.props.getActiveMenuItem() === this.props.node.id ? apiStyles.activemenuitem : "",
       this.isActive() ? apiStyles.activelink : ""
@@ -30,7 +31,7 @@ export default class ApiSubMenu extends Component {
       <li key={this.props.node.id}>
         <a href={`#${this.props.node.id}`}
           onClick={this.onUserInteraction}
-          className={this.getPrimaryLinkClassName()}>{this.props.node.name}</a>
+          className={this.getPrimaryLinkClassName()}>{upperFirst(this.props.node.name)}</a>
         <ol className={this.isActive() ? "" : apiStyles.subhidden}>
           {this.props.node.methods.map((method) => {
             return <li key={method.id}>

docs/src/components/api.js

@@ -41,14 +41,16 @@ export default class Api extends Component {
     return this.state.activeSubMenu === id
   }
 
+  hasActiveApiMenu() {
+    return this.state.activeMenuItem || this.state.activeSubMenu
+  }
+
   onVisibleEndPointGroup(id) {
-    // console.log(`Api.onVisibleEndPointGroup ${id}`)
     this.setActiveSubMenu(id)
     this.setActiveMenuItem(id)
   }
 
   onVisibleEndPoint(id) {
-    // console.log(`Api.onVisibleEndPoint ${id}`)
     this.setActiveMenuItem(id)
   }
 
@@ -62,6 +64,7 @@ export default class Api extends Component {
                 <a href={`#${node.fields.idName}`}>{node.frontmatter.title}</a>
               </li>
             })}
+
             {this.props.data.endpointScopes.edges.map(({ node }) => {
               return <ApiSubMenu
                         key={node.id} node={node}

docs/src/components/api.module.css

@@ -92,7 +92,7 @@ main h2:first-child {
   padding-left: 0;
 }
 .nav li li {
-  padding-left: 1.45rem;
+  /* padding-left: 1.45rem; */
   font-size: 0.875em;
 }
 

docs/src/pages/api/00_usage.md

@@ -0,0 +1,87 @@
+---
+title: "Usage"
+---
+
+### Node
+
+Install with `npm install @octokit/rest`.
+
+```js
+const octokit = require('@octokit/rest')()
+
+// Compare: https://developer.github.com/v3/repos/#list-organization-repositories
+octokit.repos.getForOrg({
+  org: 'octokit',
+  type: 'public'
+}).then(({ data, headers, status }) => {
+  // handle data
+})
+```
+
+### Browser
+
+1. Download `octokit-rest.min.js` from the latest release: https://github.com/octokit/rest.js/releases
+
+2. Load it as script into your web application:
+
+   ```html
+   <script src="octokit-rest.min.js"></script>
+   ```
+
+3. Initialize `octokit`
+
+   ```js
+   const octokit = new Octokit()
+
+   // Compare: https://developer.github.com/v3/repos/#list-organization-repositories
+   octokit.repos.getForOrg({
+     org: 'octokit',
+     type: 'public'
+   }).then(({data, headers, status}) => {
+     // handle data
+   })
+   ```
+
+### Client options
+
+All available client options with default values
+
+<!-- HEADS UP: when changing the options for the constructor, make sure to also
+     update the type definition templates in scripts/templates/* -->
+```js
+const Octokit = require('@octokit/rest')
+const octokit = new Octokit({
+  // see "Authentication" section below
+  auth: undefined,
+
+  // setting a user agent is required: https://developer.github.com/v3/#user-agent-required
+  // v1.2.3 will be current @octokit/rest version
+  userAgent: 'octokit/rest.js v1.2.3',
+
+  // add list of previews you’d like to enable globally,
+  // see https://developer.github.com/v3/previews/.
+  // Example: ['jean-grey', 'symmetra']
+  previews: [],
+
+  // set custom URL for on-premise GitHub Enterprise installations
+  baseUrl: 'https://api.github.com',
+
+  // pass custom methods for debug, info, warn and error
+  log: {
+    debug: () => {},
+    info: () => {},
+    warn: console.warn,
+    error: console.error
+  },
+
+  request: {
+    // Node.js only: advanced request options can be passed as http(s) agent,
+    // such as custom SSL certificate or proxy settings.
+    // See https://nodejs.org/api/http.html#http_class_http_agent
+    agent: undefined,
+
+    // request timeout in ms. 0 means no timeout
+    timeout: 0
+  }
+})
+```

docs/src/pages/api/01_authentication.md

@@ -2,10 +2,7 @@
 title: "Authentication"
 ---
 
-Most GitHub API calls don't require authentication. Rules of thumb:
-
-1. If you can see the information by visiting the site without being logged in, you don't have to be authenticated to retrieve the same information through the API.
-2. If you want to change data, you have to be authenticated.
+While authentication is not strictly required from some API endpoints, GitHub encourages to authenticated all requests to GitHub. Unauthenticated requests are subject to much more aggressive rate limiting.
 
 To enable authenticated requests, pass an `auth` option to the Octokit constructor:
 
@@ -24,16 +21,20 @@ The `auth` option can be
 
    ```js
    new Octokit({
-     auth: 'token secret123'
+     auth: 'secret123'
    })
    ```
 
-   Use this for
+   The string can be one of
 
-   - personal access tokens
-   - OAuth access tokens
-   - GitHub App bearer tokens
-   - GitHub App installation tokens
+   1. Personal access tokens  
+      You can [create personal access tokens](https://github.com/settings/tokens) in your account’s developer settings or use the "[Create a new authorization](#octokit-routes-oauthAuthorizations-create-authorization)" endpoint.
+   2. OAuth access tokens  
+      Retrieved using the [web application flow](https://developer.github.com/apps/building-oauth-apps/authorizing-oauth-apps/#web-application-flow). See also: [octokit/oauth-login-url.js](https://github.com/octokit/oauth-login-url.js).
+   3. GitHub App bearer tokens  
+      See [octokit/app.js](https://github.com/octokit/app.js) to retrieve a JSON Web Token (JWT) in order to authenticate as a GitHub App.
+   4. GitHub App installation tokens  
+      See [octokit/app.js](https://github.com/octokit/app.js) to retrieve an installation access token in order to authenticate as a GitHub App installation. Also see `4. A function` below for an example.
 
 2. As object with the properties `username`, `password`, `on2fa`.
 
@@ -55,8 +56,8 @@ The `auth` option can be
 
 3. An object with the properties `clientId` and `clientSecret`
 
-   OAuth applications can authenticate using their `clientId` and `clientSecret`
-   in order to [increase the unauthenticated rate limit](https://developer.github.com/v3/#increasing-the-unauthenticated-rate-limit-for-oauth-applications).
+   OAuth applications can authenticate using their `client_id` and `client_secret`
+   in order to [increase the unauthenticated rate limit](https://developer.github.com/v3/#increasing-the-unauthenticated-rate-limit-for-oauth-applications). Find the id and secret in your GitHub account’s developer setting, or, if the OAuth app belongs to a GitHub organization, the organization’s developer settings.
 
 4. A function
 

docs/src/pages/api/02_introduction.md

@@ -0,0 +1,26 @@
+---
+title: "Previews"
+---
+
+To enable any of [GitHub’s API Previews](https://developer.github.com/v3/previews/),
+pass the `previews` option to the GitHub constructor
+
+```js
+const octokit = new Octokit({
+  previews: [
+    'mercy-preview'
+  ]
+})
+```
+
+Previews can also be enabled for a single request by passing the `mediaType.preview` option
+
+```js
+const { data: { topics } } = await octokit.repos.get({
+  owner: 'octokit',
+  repo: 'rest.js',
+  mediaType: {
+    previews: ['symmetra']
+  }
+})
+```

docs/src/pages/api/03_request_formats.md

@@ -0,0 +1,18 @@
+---
+title: "Request formats"
+---
+
+Some API endpoints support alternative response formats, see [Media types](https://developer.github.com/v3/media/).
+
+For example, to request a [pull request as diff format](https://developer.github.com/v3/media/#diff), set the `mediaType.format` option
+
+```js
+const { data: prDiff } = await octokit.pulls.get({
+  owner: 'octokit',
+  repo: 'rest.js',
+  number: 1278,
+  mediaType: {
+    format: 'diff'
+  }
+})
+```