doc(guides) write some new guides

thomasmarshall · Oct 19, 2016 · e610d61 · e610d61
1 parent 983e23e
commit e610d61
Show file tree

Hide file tree

Showing 26 changed files with 1,379 additions and 854 deletions.
diff --git a/.gitignore b/.gitignore
@@ -14,4 +14,4 @@ _site
 .sass-cache
 .jekyll-metadata
 gh-pages/
-guides/index.md
+__*
diff --git a/.yardopts b/.yardopts
@@ -1,5 +1,5 @@
 --no-private
---markup markdown
---readme readme.md
---title 'GraphQL Ruby API Documentation'
-'lib/**/*.rb' - '**/*.md'
+--markup=markdown
+--readme=readme.md
+--title='GraphQL Ruby API Documentation'
+'lib/**/*.rb' - '*.md'
diff --git a/Rakefile b/Rakefile
@@ -18,21 +18,6 @@ end
 
 task(default: [:test, :rubocop])
 
-def load_gem_and_dummy
-  $:.push File.expand_path("../lib", __FILE__)
-  $:.push File.expand_path("../spec", __FILE__)
-  require "graphql"
-  require "./spec/support/dairy_app"
-end
-
-task :console do
-  require "irb"
-  require "irb/completion"
-  load_gem_and_dummy
-  ARGV.clear
-  IRB.start
-end
-
 desc "Use Racc & Ragel to regenerate parser.rb & lexer.rb from configuration files"
 task :build_parser do
   `rm lib/graphql/language/parser.rb lib/graphql/language/lexer.rb `
@@ -41,17 +26,8 @@ task :build_parser do
 end
 
 namespace :site do
-  task :generate_readme_index do
-    File.open("guides/index.md", "w") do |fo|
-      fo.puts "---\npermalink: \"/\"\n---\n"
-      File.foreach("readme.md") do |li|
-        fo.puts li
-      end
-    end
-  end
-
   desc "View the documentation site locally"
-  task :serve => :generate_readme_index do
+  task :serve do
     require "jekyll"
 
     # Generate the site in server mode.
@@ -67,7 +43,7 @@ namespace :site do
   end
 
   desc "Commit the local site to the gh-pages branch and publish to GitHub Pages"
-  task :publish => [:generate_readme_index, :html_proofer] do
+  task :publish => [:html_proofer] do
     # Ensure the gh-pages dir exists so we can generate into it.
     puts "Checking for gh-pages dir..."
     unless File.exist?("./gh-pages")
@@ -117,7 +93,7 @@ namespace :site do
   end
 
   desc "Test the generated HTML files"
-  task :html_proofer => :generate_readme_index do
+  task :html_proofer do
     require "html-proofer"
 
     Dir.chdir("guides") do

diff --git a/graphql.gemspec b/graphql.gemspec
@@ -14,12 +14,10 @@ Gem::Specification.new do |s|
   s.license     = "MIT"
   s.required_ruby_version = ">= 2.1.0" # bc optional keyword args
 
-  s.files = Dir["{lib}/**/*", "MIT-LICENSE", "readme.md"]
+  s.files = Dir["{lib}/**/*", "MIT-LICENSE", "readme.md", ".yardopts"]
   s.test_files = Dir["spec/**/*"]
 
   s.add_development_dependency "codeclimate-test-reporter", "~>0.4"
-  s.add_development_dependency "pry", "~> 0.10"
-  s.add_development_dependency 'pry-stack_explorer'
   s.add_development_dependency "guard", "~> 2.12"
   s.add_development_dependency "guard-bundler", "~> 2.1"
   s.add_development_dependency "guard-minitest", "~> 2.4"

diff --git a/guides/_layouts/default.html b/guides/_layouts/default.html
@@ -2,7 +2,7 @@
 <html lang="en">
   <head>
     <meta charset="utf-8">
-    <title>GraphQL Ruby</title>
+    <title>GraphQL Ruby - {{ page.title }}</title>
     <link rel="stylesheet" href="{{ site.baseurl }}/css/main.css">
     <link rel="icon" href="{{ site.baseurl }}/graphql-ruby-icon.png">
     <meta name="generator">
@@ -26,16 +26,37 @@
 
       <div class="grid -between">
         <div class="cell -3of12">
-          <h3><a href="{% if jekyll.environment == 'development' %}/{% else %}{{ site.baseurl }}{% endif %}">Readme</a></h3>
           <h3>Guides</h3>
           <ul>
-            <li><a href="{{ site.baseurl }}/introduction">Introduction</a></li>
-            <li><a href="{{ site.baseurl }}/defining_your_schema">Defining a Schema</a></li>
-            <li><a href="{{ site.baseurl }}/executing_queries">Executing Queries</a></li>
-            <li><a href="{{ site.baseurl }}/code_reuse">Code Reuse</a></li>
-            <li><a href="{{ site.baseurl }}/relay">Relay</a></li>
-            <li><a href="{{ site.baseurl }}/security">Security</a></li>
-            <li><a href="{{ site.baseurl }}/testing">Testing</a></li>
+            <li><a href="{{ site.baseurl }}/">Getting Started</a></li>
+            <li>
+              <strong>Schema</strong>
+              <ul>
+                <li><a href="{{ site.baseurl }}/schema/types_and_fields">Types and Fields</a></li>
+                <li><a href="{{ site.baseurl }}/schema/configuration_options">Configuration Options</a></li>
+                <li><a href="{{ site.baseurl }}/schema/code_reuse">Code Reuse</a></li>
+                <li><a href="{{ site.baseurl }}/schema/testing">Testing</a></li>
+              </ul>
+            </li>
+            <li>
+              <strong>Queries</strong>
+              <ul>
+                <li><a href="{{ site.baseurl }}/queries/executing_queries">Executing Queries</a></li>
+                <li><a href="{{ site.baseurl }}/queries/authorization">Authorization</a></li>
+                <li><a href="{{ site.baseurl }}/queries/security">Security</a></li>
+                <li><a href="{{ site.baseurl }}/queries/optimization">Optimization</a></li>
+                <li><a href="{{ site.baseurl }}/queries/error_handling">Error Handling</a></li>
+                <li><a href="{{ site.baseurl }}/queries/phases_of_execution">Phases of Execution</a></li>
+              </ul>
+            </li>
+            <li>
+              <strong>Relay</strong>
+              <ul>
+                <li><a href="{{ site.baseurl }}/relay/object_identification">Object Identification</a></li>
+                <li><a href="{{ site.baseurl }}/relay/connections">Connections</a></li>
+                <li><a href="{{ site.baseurl }}/relay/mutations">Mutations</a></li>
+              </ul>
+            </li>
           </ul>
           <h3><a href="http://www.rubydoc.info/github/rmosolgo/graphql-ruby">API Docs</a></h3>
           <h3><a href="https://github.com/rmosolgo/graphql-ruby">Source Code</a></h3>

diff --git a/guides/_plugins/api_doc.rb b/guides/_plugins/api_doc.rb
@@ -0,0 +1,16 @@
+module GraphQLSite
+  module APIDoc
+    API_DOC_ROOT = "http://www.rubydoc.info/gems/graphql/"
+
+    def api_doc(input)
+      doc_path = input
+        .gsub("::", "/")                        # namespaces
+        .sub(/#(.+)$/, "#\\1-instance_method")  # instance methods
+        .sub(/\.(.+)$/, "#\\1-class_method")    # class methods
+
+      %|<a href="#{API_DOC_ROOT}#{doc_path}" target="_blank"><code>#{input}</code></a>|
+    end
+  end
+end
+
+Liquid::Template.register_filter(GraphQLSite::APIDoc)
diff --git a/guides/executing_queries.md b/guides/executing_queries.md
diff --git a/guides/index.md b/guides/index.md
@@ -0,0 +1,109 @@
+---
+title: Welcome
+---
+
+## Installation
+
+You can install `graphql` from RubyGems by adding to your application's `Gemfile`:
+
+```ruby
+# Gemfile
+gem "graphql"
+```
+
+Then, running `bundle install`:
+
+```sh
+$ bundle install
+```
+
+## Getting Started
+
+Building a GraphQL server goes like this:
+
+- Define some types
+- Connect them to a schema
+- Execute queries with your schema
+
+### Declare types
+
+Types describe objects in your application and form the basis for [GraphQL's type system](http://graphql.org/learn/schema/#type-system).
+
+```ruby
+PostType = GraphQL::ObjectType.define do
+  name "Post"
+  description "A blog post"
+  # `!` marks a field as "required" or "non-null"
+  field :id, !types.ID
+  field :title, !types.String
+  field :body, !types.String
+  field :comments, types[!CommentType]
+end
+
+CommentType = GraphQL::ObjectType.define do
+  name "Comment"
+  field :id, !types.ID
+  field :body, !types.String
+  field :created_at, !types.String
+end
+```
+
+### Build a Schema
+
+Before building a schema, you have to define an [entry point to your system, the "query root"](http://graphql.org/learn/schema/#the-query-and-mutation-types):
+
+```ruby
+QueryType = GraphQL::ObjectType.define do
+  name "Query"
+  description "The query root of this schema"
+
+  field :post do
+    type PostType
+    argument :id, !types.ID
+    description "Find a Post by ID"
+    resolve -> (obj, args, ctx) { Post.find(args["id"]) }
+  end
+end
+```
+
+Then, build a schema with `QueryType` as the query entry point:
+
+```ruby
+Schema = GraphQL::Schema.define do
+  query QueryType
+end
+```
+
+This schema is ready to serve GraphQL queries! See ["Configuration Options"]({{ site.baseurl }}/schema/configuration_options) for all the schema options.
+
+### Execute queries
+
+You can execute queries from a query string:
+
+```ruby
+query_string = "
+{
+  post(id: 1) {
+    id
+    title
+  }
+}"
+result_hash = Schema.execute(query_string)
+# {
+#   "data" => {
+#     "post" => {
+#        "id" => 1,
+#        "title" => "GraphQL is nice"
+#     }
+#   }
+# }
+```
+
+See ["Executing Queries"]({{ site.baseurl }}/queries/executing_queries) for more information about running queries on your schema.
+
+## Use with Relay
+
+If you're building a backend for [Relay](http://facebook.github.io/relay/), you'll need:
+
+- A JSON dump of the schema, which you can get by sending [`GraphQL::Introspection::INTROSPECTION_QUERY`](https://github.com/rmosolgo/graphql-ruby/blob/master/lib/graphql/introspection/introspection_query.rb)
+- Relay-specific helpers for GraphQL, see the `GraphQL::Relay` guides.