Skip to content

Commit e610d61

Browse files
rmosolgormosolgo
committed
doc(guides) write some new guides
1 parent 983e23e commit e610d61

26 files changed

+1379
-854
lines changed

‎.gitignore

+1-1
Original file line numberDiff line numberDiff line change
@@ -14,4 +14,4 @@ _site
1414
.sass-cache
1515
.jekyll-metadata
1616
gh-pages/
17-
guides/index.md
17+
__*

‎.yardopts

+4-4
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
--no-private
2-
--markup markdown
3-
--readme readme.md
4-
--title 'GraphQL Ruby API Documentation'
5-
'lib/**/*.rb' - '**/*.md'
2+
--markup=markdown
3+
--readme=readme.md
4+
--title='GraphQL Ruby API Documentation'
5+
'lib/**/*.rb' - '*.md'

‎Rakefile

+3-27
Original file line numberDiff line numberDiff line change
@@ -18,21 +18,6 @@ end
1818

1919
task(default: [:test, :rubocop])
2020

21-
def load_gem_and_dummy
22-
$:.push File.expand_path("../lib", __FILE__)
23-
$:.push File.expand_path("../spec", __FILE__)
24-
require "graphql"
25-
require "./spec/support/dairy_app"
26-
end
27-
28-
task :console do
29-
require "irb"
30-
require "irb/completion"
31-
load_gem_and_dummy
32-
ARGV.clear
33-
IRB.start
34-
end
35-
3621
desc "Use Racc & Ragel to regenerate parser.rb & lexer.rb from configuration files"
3722
task :build_parser do
3823
`rm lib/graphql/language/parser.rb lib/graphql/language/lexer.rb `
@@ -41,17 +26,8 @@ task :build_parser do
4126
end
4227

4328
namespace :site do
44-
task :generate_readme_index do
45-
File.open("guides/index.md", "w") do |fo|
46-
fo.puts "---\npermalink: \"/\"\n---\n"
47-
File.foreach("readme.md") do |li|
48-
fo.puts li
49-
end
50-
end
51-
end
52-
5329
desc "View the documentation site locally"
54-
task :serve => :generate_readme_index do
30+
task :serve do
5531
require "jekyll"
5632

5733
# Generate the site in server mode.
@@ -67,7 +43,7 @@ namespace :site do
6743
end
6844

6945
desc "Commit the local site to the gh-pages branch and publish to GitHub Pages"
70-
task :publish => [:generate_readme_index, :html_proofer] do
46+
task :publish => [:html_proofer] do
7147
# Ensure the gh-pages dir exists so we can generate into it.
7248
puts "Checking for gh-pages dir..."
7349
unless File.exist?("./gh-pages")
@@ -117,7 +93,7 @@ namespace :site do
11793
end
11894

11995
desc "Test the generated HTML files"
120-
task :html_proofer => :generate_readme_index do
96+
task :html_proofer do
12197
require "html-proofer"
12298

12399
Dir.chdir("guides") do

‎graphql.gemspec

+1-3
Original file line numberDiff line numberDiff line change
@@ -14,12 +14,10 @@ Gem::Specification.new do |s|
1414
s.license = "MIT"
1515
s.required_ruby_version = ">= 2.1.0" # bc optional keyword args
1616

17-
s.files = Dir["{lib}/**/*", "MIT-LICENSE", "readme.md"]
17+
s.files = Dir["{lib}/**/*", "MIT-LICENSE", "readme.md", ".yardopts"]
1818
s.test_files = Dir["spec/**/*"]
1919

2020
s.add_development_dependency "codeclimate-test-reporter", "~>0.4"
21-
s.add_development_dependency "pry", "~> 0.10"
22-
s.add_development_dependency 'pry-stack_explorer'
2321
s.add_development_dependency "guard", "~> 2.12"
2422
s.add_development_dependency "guard-bundler", "~> 2.1"
2523
s.add_development_dependency "guard-minitest", "~> 2.4"

‎guides/_layouts/default.html

+30-9
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
<html lang="en">
33
<head>
44
<meta charset="utf-8">
5-
<title>GraphQL Ruby</title>
5+
<title>GraphQL Ruby - {{ page.title }}</title>
66
<link rel="stylesheet" href="{{ site.baseurl }}/css/main.css">
77
<link rel="icon" href="{{ site.baseurl }}/graphql-ruby-icon.png">
88
<meta name="generator">
@@ -26,16 +26,37 @@
2626

2727
<div class="grid -between">
2828
<div class="cell -3of12">
29-
<h3><a href="{% if jekyll.environment == 'development' %}/{% else %}{{ site.baseurl }}{% endif %}">Readme</a></h3>
3029
<h3>Guides</h3>
3130
<ul>
32-
<li><a href="{{ site.baseurl }}/introduction">Introduction</a></li>
33-
<li><a href="{{ site.baseurl }}/defining_your_schema">Defining a Schema</a></li>
34-
<li><a href="{{ site.baseurl }}/executing_queries">Executing Queries</a></li>
35-
<li><a href="{{ site.baseurl }}/code_reuse">Code Reuse</a></li>
36-
<li><a href="{{ site.baseurl }}/relay">Relay</a></li>
37-
<li><a href="{{ site.baseurl }}/security">Security</a></li>
38-
<li><a href="{{ site.baseurl }}/testing">Testing</a></li>
31+
<li><a href="{{ site.baseurl }}/">Getting Started</a></li>
32+
<li>
33+
<strong>Schema</strong>
34+
<ul>
35+
<li><a href="{{ site.baseurl }}/schema/types_and_fields">Types and Fields</a></li>
36+
<li><a href="{{ site.baseurl }}/schema/configuration_options">Configuration Options</a></li>
37+
<li><a href="{{ site.baseurl }}/schema/code_reuse">Code Reuse</a></li>
38+
<li><a href="{{ site.baseurl }}/schema/testing">Testing</a></li>
39+
</ul>
40+
</li>
41+
<li>
42+
<strong>Queries</strong>
43+
<ul>
44+
<li><a href="{{ site.baseurl }}/queries/executing_queries">Executing Queries</a></li>
45+
<li><a href="{{ site.baseurl }}/queries/authorization">Authorization</a></li>
46+
<li><a href="{{ site.baseurl }}/queries/security">Security</a></li>
47+
<li><a href="{{ site.baseurl }}/queries/optimization">Optimization</a></li>
48+
<li><a href="{{ site.baseurl }}/queries/error_handling">Error Handling</a></li>
49+
<li><a href="{{ site.baseurl }}/queries/phases_of_execution">Phases of Execution</a></li>
50+
</ul>
51+
</li>
52+
<li>
53+
<strong>Relay</strong>
54+
<ul>
55+
<li><a href="{{ site.baseurl }}/relay/object_identification">Object Identification</a></li>
56+
<li><a href="{{ site.baseurl }}/relay/connections">Connections</a></li>
57+
<li><a href="{{ site.baseurl }}/relay/mutations">Mutations</a></li>
58+
</ul>
59+
</li>
3960
</ul>
4061
<h3><a href="http://www.rubydoc.info/github/rmosolgo/graphql-ruby">API Docs</a></h3>
4162
<h3><a href="https://github.com/rmosolgo/graphql-ruby">Source Code</a></h3>

‎guides/_plugins/api_doc.rb

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
module GraphQLSite
2+
module APIDoc
3+
API_DOC_ROOT = "http://www.rubydoc.info/gems/graphql/"
4+
5+
def api_doc(input)
6+
doc_path = input
7+
.gsub("::", "/") # namespaces
8+
.sub(/#(.+)$/, "#\\1-instance_method") # instance methods
9+
.sub(/\.(.+)$/, "#\\1-class_method") # class methods
10+
11+
%|<a href="#{API_DOC_ROOT}#{doc_path}" target="_blank"><code>#{input}</code></a>|
12+
end
13+
end
14+
end
15+
16+
Liquid::Template.register_filter(GraphQLSite::APIDoc)

‎guides/executing_queries.md

-92
This file was deleted.

‎guides/index.md

+109
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
---
2+
title: Welcome
3+
---
4+
5+
## Installation
6+
7+
You can install `graphql` from RubyGems by adding to your application's `Gemfile`:
8+
9+
```ruby
10+
# Gemfile
11+
gem "graphql"
12+
```
13+
14+
Then, running `bundle install`:
15+
16+
```sh
17+
$ bundle install
18+
```
19+
20+
## Getting Started
21+
22+
Building a GraphQL server goes like this:
23+
24+
- Define some types
25+
- Connect them to a schema
26+
- Execute queries with your schema
27+
28+
### Declare types
29+
30+
Types describe objects in your application and form the basis for [GraphQL's type system](http://graphql.org/learn/schema/#type-system).
31+
32+
```ruby
33+
PostType = GraphQL::ObjectType.define do
34+
name "Post"
35+
description "A blog post"
36+
# `!` marks a field as "required" or "non-null"
37+
field :id, !types.ID
38+
field :title, !types.String
39+
field :body, !types.String
40+
field :comments, types[!CommentType]
41+
end
42+
43+
CommentType = GraphQL::ObjectType.define do
44+
name "Comment"
45+
field :id, !types.ID
46+
field :body, !types.String
47+
field :created_at, !types.String
48+
end
49+
```
50+
51+
### Build a Schema
52+
53+
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):
54+
55+
```ruby
56+
QueryType = GraphQL::ObjectType.define do
57+
name "Query"
58+
description "The query root of this schema"
59+
60+
field :post do
61+
type PostType
62+
argument :id, !types.ID
63+
description "Find a Post by ID"
64+
resolve -> (obj, args, ctx) { Post.find(args["id"]) }
65+
end
66+
end
67+
```
68+
69+
Then, build a schema with `QueryType` as the query entry point:
70+
71+
```ruby
72+
Schema = GraphQL::Schema.define do
73+
query QueryType
74+
end
75+
```
76+
77+
This schema is ready to serve GraphQL queries! See ["Configuration Options"]({{ site.baseurl }}/schema/configuration_options) for all the schema options.
78+
79+
### Execute queries
80+
81+
You can execute queries from a query string:
82+
83+
```ruby
84+
query_string = "
85+
{
86+
post(id: 1) {
87+
id
88+
title
89+
}
90+
}"
91+
result_hash = Schema.execute(query_string)
92+
# {
93+
# "data" => {
94+
# "post" => {
95+
# "id" => 1,
96+
# "title" => "GraphQL is nice"
97+
# }
98+
# }
99+
# }
100+
```
101+
102+
See ["Executing Queries"]({{ site.baseurl }}/queries/executing_queries) for more information about running queries on your schema.
103+
104+
## Use with Relay
105+
106+
If you're building a backend for [Relay](http://facebook.github.io/relay/), you'll need:
107+
108+
- 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)
109+
- Relay-specific helpers for GraphQL, see the `GraphQL::Relay` guides.

0 commit comments

Comments
 (0)