From 4d7299410a78e4bec988cdef71ec1309566f75bb Mon Sep 17 00:00:00 2001 From: Kevin Lacker Date: Thu, 8 Sep 2016 16:14:25 -0700 Subject: [PATCH 1/3] add a sidebar --- site/_core/DocsSidebar.js | 13 +++++++++---- site/code/index.html.js | 11 ++++++++--- site/docs/APIReference-Errors.md | 2 +- site/docs/APIReference-Execution.md | 2 +- site/docs/APIReference-GraphQL.md | 2 +- site/docs/APIReference-Language.md | 2 +- site/docs/APIReference-TypeSystem.md | 2 +- site/docs/APIReference-Utilities.md | 2 +- site/docs/APIReference-Validation.md | 2 +- site/docs/Guides-ConstructingTypes.md | 5 +++-- site/docs/Tutorial-Authentication.md | 5 +++-- site/docs/Tutorial-BasicTypes.md | 4 ++-- site/docs/Tutorial-ExpressGraphQL.md | 5 +++-- site/docs/Tutorial-GettingStarted.md | 15 ++++++--------- site/docs/Tutorial-GraphQLClients.md | 4 ++-- site/docs/Tutorial-Mutations.md | 4 ++-- site/docs/Tutorial-ObjectTypes.md | 4 ++-- site/docs/Tutorial-PassingArguments.md | 4 ++-- 18 files changed, 49 insertions(+), 39 deletions(-) diff --git a/site/_core/DocsSidebar.js b/site/_core/DocsSidebar.js index 56f2d10910..c5fd6c5f92 100644 --- a/site/_core/DocsSidebar.js +++ b/site/_core/DocsSidebar.js @@ -11,7 +11,7 @@ var React = require('react'); var DocsSidebar = React.createClass({ render: function() { return
- {getCategories(this.props.site).map((category) => + {getCategories(this.props.site, this.props.firstURL).map((category) =>

{category.name}

    @@ -22,7 +22,7 @@ var DocsSidebar = React.createClass({ style={{marginLeft: page.indent ? 20 : 0}} className={page.id === this.props.page.id ? 'active' : ''} href={page.url}> - {page.title} + {page.sidebarTitle || page.title} )} @@ -33,7 +33,9 @@ var DocsSidebar = React.createClass({ } }); -function getCategories(site) { +// If firstURL is provided, it's the URL (starting with /) of the +// first page to put on the sidebar. +function getCategories(site, firstURL) { var pages = site.files.docs.filter(file => file.content); // Build a hashmap of url -> page @@ -61,11 +63,14 @@ function getCategories(site) { var first = null; for (var i = 0; i < pages.length; ++i) { var page = pages[i]; - if (!previous[page.url]) { + if (firstURL ? (firstURL === page.url) : !previous[page.url]) { first = page; break; } } + if (!first) { + throw new Error('first not found'); + } var categories = []; var currentCategory = null; diff --git a/site/code/index.html.js b/site/code/index.html.js index f9779172e5..95bad03dc2 100644 --- a/site/code/index.html.js +++ b/site/code/index.html.js @@ -9,13 +9,18 @@ var React = require('react'); var Site = require('../_core/Site'); var Marked = require('../_core/Marked'); +var DocsSidebar = require('../_core/DocsSidebar'); var Code = React.createClass({ render: function() { + var page = this.props.page; + var site = this.props.site; + var firstURL = '/graphql-js/getting-started/'; return ( -
    +
    +

    Code

    {` @@ -24,8 +29,8 @@ Many different programming languages support GraphQL. This list contains some of ## GraphQL Server Libraries - - [GraphQL.js](/graphql-js/) ([github](https://github.com/graphql/graphql-js)) ([npm](https://www.npmjs.com/package/graphql)): The reference implementation of the GraphQL specification, designed for running a GraphQL server in a Node.js environment. - - [express-graphql](/graphql-js/) ([github](https://github.com/graphql/express-graphql)) ([npm](https://www.npmjs.com/package/express-graphql)): The reference implementation of a GraphQL API server over an Express webserver. You can use this to run GraphQL in conjunction with a regular Express webserver, or as a standalone GraphQL server. + - [GraphQL.js](/graphql-js/getting-started/) ([github](https://github.com/graphql/graphql-js/)) ([npm](https://www.npmjs.com/package/graphql)): The reference implementation of the GraphQL specification, designed for running a GraphQL server in a Node.js environment. + - [express-graphql](/graphql-js/getting-started/) ([github](https://github.com/graphql/express-graphql)) ([npm](https://www.npmjs.com/package/express-graphql)): The reference implementation of a GraphQL API server over an Express webserver. You can use this to run GraphQL in conjunction with a regular Express webserver, or as a standalone GraphQL server. - [Graphene](http://graphene-python.org/) ([github](https://github.com/graphql-python/graphene)): A Python library for building GraphQL APIs. Built-in support for [Relay](https://facebook.github.io/relay/), Django, SQLAlchemy, and Google App Engine. - [graphql-ruby](https://github.com/rmosolgo/graphql-ruby): A Ruby library for building GraphQL APIs. Built-in support for Relay and Rails. - [graphql-java](https://github.com/graphql-java/graphql-java): A Java library for building GraphQL APIs. diff --git a/site/docs/APIReference-Errors.md b/site/docs/APIReference-Errors.md index ec874b3c81..70fa0f4a3f 100644 --- a/site/docs/APIReference-Errors.md +++ b/site/docs/APIReference-Errors.md @@ -1,6 +1,6 @@ --- title: Errors -layout: ../_core/DocsLayout +layout: ../_core/CodeLayout category: API Reference permalink: /docs/api-reference-errors/ next: /docs/api-reference-utilities/ diff --git a/site/docs/APIReference-Execution.md b/site/docs/APIReference-Execution.md index 3c07108e00..3c54c9de4d 100644 --- a/site/docs/APIReference-Execution.md +++ b/site/docs/APIReference-Execution.md @@ -1,6 +1,6 @@ --- title: Execution -layout: ../_core/DocsLayout +layout: ../_core/CodeLayout category: API Reference permalink: /docs/api-reference-execution/ next: /docs/api-reference-errors/ diff --git a/site/docs/APIReference-GraphQL.md b/site/docs/APIReference-GraphQL.md index 57906758e1..9495c569f6 100644 --- a/site/docs/APIReference-GraphQL.md +++ b/site/docs/APIReference-GraphQL.md @@ -1,6 +1,6 @@ --- title: GraphQL -layout: ../_core/DocsLayout +layout: ../_core/CodeLayout category: API Reference permalink: /docs/api-reference-graphql/ next: /docs/api-reference-language/ diff --git a/site/docs/APIReference-Language.md b/site/docs/APIReference-Language.md index a20908e09b..853e5f1433 100644 --- a/site/docs/APIReference-Language.md +++ b/site/docs/APIReference-Language.md @@ -1,6 +1,6 @@ --- title: Language -layout: ../_core/DocsLayout +layout: ../_core/CodeLayout category: API Reference permalink: /docs/api-reference-language/ next: /docs/api-reference-type-system/ diff --git a/site/docs/APIReference-TypeSystem.md b/site/docs/APIReference-TypeSystem.md index 66504f2c5f..2d61f5e916 100644 --- a/site/docs/APIReference-TypeSystem.md +++ b/site/docs/APIReference-TypeSystem.md @@ -1,6 +1,6 @@ --- title: Type System -layout: ../_core/DocsLayout +layout: ../_core/CodeLayout category: API Reference permalink: /docs/api-reference-type-system/ next: /docs/api-reference-validation/ diff --git a/site/docs/APIReference-Utilities.md b/site/docs/APIReference-Utilities.md index 27ea0c39d5..e66356e91e 100644 --- a/site/docs/APIReference-Utilities.md +++ b/site/docs/APIReference-Utilities.md @@ -1,6 +1,6 @@ --- title: Utilities -layout: ../_core/DocsLayout +layout: ../_core/CodeLayout category: API Reference permalink: /docs/api-reference-utilities/ --- diff --git a/site/docs/APIReference-Validation.md b/site/docs/APIReference-Validation.md index 92014f1334..ba8e67f750 100644 --- a/site/docs/APIReference-Validation.md +++ b/site/docs/APIReference-Validation.md @@ -1,6 +1,6 @@ --- title: Validation -layout: ../_core/DocsLayout +layout: ../_core/CodeLayout category: API Reference permalink: /docs/api-reference-validation/ next: /docs/api-reference-execution/ diff --git a/site/docs/Guides-ConstructingTypes.md b/site/docs/Guides-ConstructingTypes.md index 6ed778987c..2eec752545 100644 --- a/site/docs/Guides-ConstructingTypes.md +++ b/site/docs/Guides-ConstructingTypes.md @@ -1,8 +1,9 @@ --- title: Constructing Types -layout: ../_core/DocsLayout -category: Guides +layout: ../_core/CodeLayout +category: Advanced Guides permalink: /graphql-js/constructing-types/ +next: /docs/api-reference-graphql/ --- For many apps, you can define a fixed schema when the application starts, and define it using GraphQL schema language. In some cases, it's useful to construct a schema programmatically. You can do this using the `GraphQLSchema` constructor. diff --git a/site/docs/Tutorial-Authentication.md b/site/docs/Tutorial-Authentication.md index 1a71390f30..495f323506 100644 --- a/site/docs/Tutorial-Authentication.md +++ b/site/docs/Tutorial-Authentication.md @@ -1,7 +1,8 @@ --- title: Authentication and Express Middleware -layout: ../_core/DocsLayout -category: Tutorial +sidebarTitle: Authentication & Middleware +layout: ../_core/CodeLayout +category: GraphQL.js Tutorial permalink: /graphql-js/authentication-and-express-middleware/ next: /graphql-js/constructing-types/ --- diff --git a/site/docs/Tutorial-BasicTypes.md b/site/docs/Tutorial-BasicTypes.md index 1b4937f3e1..0e650624e3 100644 --- a/site/docs/Tutorial-BasicTypes.md +++ b/site/docs/Tutorial-BasicTypes.md @@ -1,7 +1,7 @@ --- title: Basic Types -layout: ../_core/DocsLayout -category: Tutorial +layout: ../_core/CodeLayout +category: GraphQL.js Tutorial permalink: /graphql-js/basic-types/ next: /graphql-js/passing-arguments/ --- diff --git a/site/docs/Tutorial-ExpressGraphQL.md b/site/docs/Tutorial-ExpressGraphQL.md index 0901e4db40..afafeae482 100644 --- a/site/docs/Tutorial-ExpressGraphQL.md +++ b/site/docs/Tutorial-ExpressGraphQL.md @@ -1,7 +1,8 @@ --- title: Running an Express GraphQL Server -layout: ../_core/DocsLayout -category: Tutorial +sidebarTitle: Running Express + GraphQL +layout: ../_core/CodeLayout +category: GraphQL.js Tutorial permalink: /graphql-js/running-an-express-graphql-server/ next: /graphql-js/graphql-clients/ --- diff --git a/site/docs/Tutorial-GettingStarted.md b/site/docs/Tutorial-GettingStarted.md index 20da77de77..bb0efec04c 100644 --- a/site/docs/Tutorial-GettingStarted.md +++ b/site/docs/Tutorial-GettingStarted.md @@ -1,18 +1,15 @@ --- -title: Getting Started -layout: ../_core/DocsLayout -category: Tutorial +title: Getting Started With GraphQL.js +sidebarTitle: Getting Started +layout: ../_core/CodeLayout +category: GraphQL.js Tutorial permalink: /graphql-js/getting-started/ next: /graphql-js/running-an-express-graphql-server/ --- ## Prerequisites -Before getting started, you should have Node v6 installed, although the examples should mostly work in previous versions of Node as well. For this guide, we won't use any language features that require transpilation, but we will use some ES6 features like Promises, classes, and fat arrow functions, so if you aren't familiar with them you might want to read up on them first. - -* Promises: http://www.html5rocks.com/en/tutorials/es6/promises/ -* Classes: http://javascriptplayground.com/blog/2014/07/introduction-to-es6-classes-tutorial/ -* Fat arrow functions: https://strongloop.com/strongblog/an-introduction-to-javascript-es6-arrow-functions/ +Before getting started, you should have Node v6 installed, although the examples should mostly work in previous versions of Node as well. For this guide, we won't use any language features that require transpilation, but we will use some ES6 features like [Promises](http://www.html5rocks.com/en/tutorials/es6/promises/), [classes](http://javascriptplayground.com/blog/2014/07/introduction-to-es6-classes-tutorial/), and [fat arrow functions](https://strongloop.com/strongblog/an-introduction-to-javascript-es6-arrow-functions/), so if you aren't familiar with them you might want to read up on them first. To create a new project and install GraphQL.js in your current directory: @@ -62,4 +59,4 @@ You should see the GraphQL response printed out: Congratulations - you just executed a GraphQL query! -For practical applications, you'll probably want to run GraphQL queries from an API server, rather than executing GraphQL with a command line tool. To use GraphQL for an API server over HTTP, check out [Running an Express-GraphQL Server](/graphql-js/running-an-express-graphql-server/). +For practical applications, you'll probably want to run GraphQL queries from an API server, rather than executing GraphQL with a command line tool. To use GraphQL for an API server over HTTP, check out [Running an Express GraphQL Server](/graphql-js/running-an-express-graphql-server/). diff --git a/site/docs/Tutorial-GraphQLClients.md b/site/docs/Tutorial-GraphQLClients.md index 1bbb5b1b66..dd816b2fef 100644 --- a/site/docs/Tutorial-GraphQLClients.md +++ b/site/docs/Tutorial-GraphQLClients.md @@ -1,7 +1,7 @@ --- title: GraphQL Clients -layout: ../_core/DocsLayout -category: Tutorial +layout: ../_core/CodeLayout +category: GraphQL.js Tutorial permalink: /graphql-js/graphql-clients/ next: /graphql-js/basic-types/ --- diff --git a/site/docs/Tutorial-Mutations.md b/site/docs/Tutorial-Mutations.md index 97744ac192..edaee8a2a7 100644 --- a/site/docs/Tutorial-Mutations.md +++ b/site/docs/Tutorial-Mutations.md @@ -1,7 +1,7 @@ --- title: Mutations and Input Types -layout: ../_core/DocsLayout -category: Tutorial +layout: ../_core/CodeLayout +category: GraphQL.js Tutorial permalink: /graphql-js/mutations-and-input-types/ next: /graphql-js/authentication-and-express-middleware/ --- diff --git a/site/docs/Tutorial-ObjectTypes.md b/site/docs/Tutorial-ObjectTypes.md index 2139d86bc7..9822cae3b2 100644 --- a/site/docs/Tutorial-ObjectTypes.md +++ b/site/docs/Tutorial-ObjectTypes.md @@ -1,7 +1,7 @@ --- title: Object Types -layout: ../_core/DocsLayout -category: Tutorial +layout: ../_core/CodeLayout +category: GraphQL.js Tutorial permalink: /graphql-js/object-types/ next: /graphql-js/mutations-and-input-types/ --- diff --git a/site/docs/Tutorial-PassingArguments.md b/site/docs/Tutorial-PassingArguments.md index c36ad7fc53..aad6a3b67b 100644 --- a/site/docs/Tutorial-PassingArguments.md +++ b/site/docs/Tutorial-PassingArguments.md @@ -1,7 +1,7 @@ --- title: Passing Arguments -layout: ../_core/DocsLayout -category: Tutorial +layout: ../_core/CodeLayout +category: GraphQL.js Tutorial permalink: /graphql-js/passing-arguments/ next: /graphql-js/object-types/ --- From 8a52a8d89bddfc68d0cac1af548b48201ab6707c Mon Sep 17 00:00:00 2001 From: Kevin Lacker Date: Thu, 8 Sep 2016 16:14:36 -0700 Subject: [PATCH 2/3] CodeLayout for code sidebar --- site/_core/CodeLayout.js | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 site/_core/CodeLayout.js diff --git a/site/_core/CodeLayout.js b/site/_core/CodeLayout.js new file mode 100644 index 0000000000..a1544937fe --- /dev/null +++ b/site/_core/CodeLayout.js @@ -0,0 +1,38 @@ +/** + * Copyright (c) 2016, Facebook, Inc. + * All rights reserved. + * + * This source code is licensed under the license found in the + * LICENSE file in the root directory of this source tree. + */ + +var path = require('path'); +var React = require('react'); +var Site = require('./Site'); +var Marked = require('./Marked'); +var DocsSidebar = require('./DocsSidebar'); + +var CodeLayout = React.createClass({ + render: function() { + var page = this.props.page; + var site = this.props.site; + var firstURL = '/graphql-js/getting-started/'; + return ( + +
    + +
    +

    {page.title}

    + {page.content} +
    + {page.previous && ← Prev} + {page.next && Next →} +
    +
    +
    +     + ); + } +}); + +module.exports = CodeLayout; From b98f82ef66c21d66057296395a17c5ffb163d959 Mon Sep 17 00:00:00 2001 From: Kevin Lacker Date: Thu, 8 Sep 2016 16:39:59 -0700 Subject: [PATCH 3/3] clean up naming of GraphQL.js --- site/docs/APIReference-Utilities.md | 4 ++-- site/docs/QuickStart-Videos.md | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/site/docs/APIReference-Utilities.md b/site/docs/APIReference-Utilities.md index e66356e91e..1a3722d0d5 100644 --- a/site/docs/APIReference-Utilities.md +++ b/site/docs/APIReference-Utilities.md @@ -117,7 +117,7 @@ function buildClientSchema( Build a GraphQLSchema for use by client tools. Given the result of a client running the introspection query, creates and -returns a GraphQLSchema instance which can be then used with all graphql-js +returns a GraphQLSchema instance which can be then used with all GraphQL.js tools, but cannot be used to execute a query, as introspection does not represent the "resolver", "parse" or "serialize" functions or any other server-internal mechanisms. @@ -152,7 +152,7 @@ function buildASTSchema( This takes the ast of a schema document produced by `parseSchemaIntoAST` in `graphql/language/schema` and constructs a GraphQLSchema instance which can be -then used with all graphql-js tools, but cannot be used to execute a query, as +then used with all GraphQL.js tools, but cannot be used to execute a query, as introspection does not represent the "resolver", "parse" or "serialize" functions or any other server-internal mechanisms. diff --git a/site/docs/QuickStart-Videos.md b/site/docs/QuickStart-Videos.md index 5a56d237d1..a4c1c12637 100644 --- a/site/docs/QuickStart-Videos.md +++ b/site/docs/QuickStart-Videos.md @@ -41,7 +41,7 @@ GraphiQL, an in-browser GraphQL IDE. *Nick Schrock – August 24, 2015* -Nick expands on Lee's talk, explaining how to use graphql-js to build a server. +Nick expands on Lee's talk, explaining how to use GraphQL.js to build a server. Then introduces how wrapping an existing REST server can be an effective way to get started with GraphQL and announces the public release of "swapi-graphql" a wrapper of the Star Wars REST API to illustrate. Many live demos of "swapi-graphql" @@ -54,7 +54,7 @@ using GraphiQL. *Lee Byron – July 2, 2015* Lee introduces GraphQL and its origin and announces the public release of the -GraphQL working draft specification and "graphql-js" a reference implementation. +GraphQL working draft specification and "GraphQL.js" a reference implementation. @@ -62,7 +62,7 @@ GraphQL working draft specification and "graphql-js" a reference implementation. *Nick Schrock, Dan Schafer – July 3, 2015* -Nick and Dan expands on Lee's talk, explaining how to use graphql-js to build a +Nick and Dan expands on Lee's talk, explaining how to use GraphQL.js to build a server and explain the merits of a strong type system.