Merge pull request #19 from gjtorikian/query-is-root

gjtorikian · web-flow · commit fdc62e4c9cf8 · 2017-05-21T21:24:21.000-04:00
Set query as a top-level item
diff --git a/.travis.yml b/.travis.yml
@@ -1,9 +1,26 @@
 language: ruby
 rvm:
-  - 2.3.1
+  - 2.3.4
+  - 2.4.0
+
+git:
+  depth: 10
+
+env:
+  global:
+    - NOKOGIRI_USE_SYSTEM_LIBRARIES=true
 
 sudo: false
 cache: bundler
 
-git:
-  depth: 10
+addons:
+  apt:
+    sources:
+      - kalakris-cmake
+    packages:
+      - cmake
+
+matrix:
+  include:
+    - script: bundle exec rake rubocop
+      rvm: 2.4.0
diff --git a/README.md b/README.md
@@ -134,7 +134,8 @@ The following options are available:
 | `delete_output` | Deletes `output_dir` before generating content. | `false` |
 | `pipeline_config` | Defines two sub-keys, `pipeline` and `context`, which are used by `html-pipeline` when rendering your output. | `pipeline` has `ExtendedMarkdownFilter`, `EmojiFilter`, and `TableOfContentsFilter`. `context` has `gfm: false` and `asset_root` set to GitHub's CDN. |
 | `renderer` | The rendering class to use. | `GraphQLDocs::Renderer`
-| `templates` | The templates to use when generating HTML. You may override any of the following keys: `includes`, `objects`, `mutations`, `interfaces`, `enums`, `unions`, `input_objects`, `scalars`, `index`. | The defaults are found in _lib/graphql-docs/layouts/_.
+| `templates` | The templates to use when generating HTML. You may override any of the following keys: `default`, `includes`, `objects`, `mutations`, `interfaces`, `enums`, `unions`, `input_objects`, `scalars`. | The defaults are found in _lib/graphql-docs/layouts/_.
+| `landing_pages` | The landing page to use when generating HTML for each type. You may override any of the following keys: `index`, `query`, `object`, `mutation`, `interface`, `enum`, `union`, `input_object`, `scalar`. | The defaults are found in _lib/graphql-docs/layouts/_.
 | `classes` | Additional class names you can provide to certain elements. | The full list is found in _lib/graphql-docs/configuration.rb/_.
 
 ## Development
diff --git a/Rakefile b/Rakefile
@@ -1,6 +1,10 @@
 require 'bundler/gem_tasks'
 require 'rake/testtask'
 
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new(:rubocop)
+
 Rake::TestTask.new(:test) do |t|
   t.libs << 'test'
   t.libs << 'lib'
@@ -33,7 +37,7 @@ task :generate_sample, [:base_url] do |task, args|
   GraphQLDocs.build(options)
 end
 
-task :sample => [:generate_sample] do
+task sample: [:generate_sample] do
   require 'webrick'
 
   puts 'Navigate to http://localhost:3000 to see the sample docs'
diff --git a/lib/graphql-docs.rb b/lib/graphql-docs.rb
@@ -1,3 +1,4 @@
+# rubocop:disable Style/FileName
 require 'graphql-docs/client'
 require 'graphql-docs/helpers'
 require 'graphql-docs/renderer'
diff --git a/lib/graphql-docs/configuration.rb b/lib/graphql-docs/configuration.rb
@@ -36,8 +36,18 @@ module Configuration
         unions: "#{File.dirname(__FILE__)}/layouts/graphql_unions.html",
         input_objects: "#{File.dirname(__FILE__)}/layouts/graphql_input_objects.html",
         scalars: "#{File.dirname(__FILE__)}/layouts/graphql_scalars.html",
+      },
 
-        index: "#{File.dirname(__FILE__)}/layouts/index.md",
+      landing_pages: {
+        index: "#{File.dirname(__FILE__)}/landing_pages/index.md",
+        query: "#{File.dirname(__FILE__)}/landing_pages/query.md",
+        object: "#{File.dirname(__FILE__)}/landing_pages/object.md",
+        mutation: "#{File.dirname(__FILE__)}/landing_pages/mutation.md",
+        interface: "#{File.dirname(__FILE__)}/landing_pages/interface.md",
+        enum: "#{File.dirname(__FILE__)}/landing_pages/enum.md",
+        union: "#{File.dirname(__FILE__)}/landing_pages/union.md",
+        input_object: "#{File.dirname(__FILE__)}/landing_pages/input_object.md",
+        scalar: "#{File.dirname(__FILE__)}/landing_pages/scalar.md"
       },
 
       classes: {
diff --git a/lib/graphql-docs/generator.rb b/lib/graphql-docs/generator.rb
@@ -33,8 +33,36 @@ def generate
       create_graphql_input_object_pages
       create_graphql_scalar_pages
 
-      unless @options[:templates][:index].nil?
-        write_file('static', 'index', File.read(@options[:templates][:index]))
+      unless @options[:landing_pages][:index].nil?
+        write_file('static', 'index', File.read(@options[:landing_pages][:index]))
+      end
+
+      unless @options[:landing_pages][:object].nil?
+        write_file('static', 'object', File.read(@options[:landing_pages][:object]))
+      end
+
+      unless @options[:landing_pages][:mutation].nil?
+        write_file('static', 'mutation', File.read(@options[:landing_pages][:mutation]))
+      end
+
+      unless @options[:landing_pages][:interface].nil?
+        write_file('static', 'interface', File.read(@options[:landing_pages][:interface]))
+      end
+
+      unless @options[:landing_pages][:enum].nil?
+        write_file('static', 'enum', File.read(@options[:landing_pages][:enum]))
+      end
+
+      unless @options[:landing_pages][:union].nil?
+        write_file('static', 'union', File.read(@options[:landing_pages][:union]))
+      end
+
+      unless @options[:landing_pages][:input_object].nil?
+        write_file('static', 'input_object', File.read(@options[:landing_pages][:input_object]))
+      end
+
+      unless @options[:landing_pages][:scalar].nil?
+        write_file('static', 'scalar', File.read(@options[:landing_pages][:scalar]))
       end
 
       if @options[:use_default_styles]
@@ -54,9 +82,32 @@ def generate
     def create_graphql_object_pages
       graphql_object_types.each do |object_type|
         next if object_type['name'].start_with?('__')
-        opts = default_generator_options(type: object_type)
-        contents = @graphql_object_template.result(OpenStruct.new(opts).instance_eval { binding })
-        write_file('object', object_type['name'], contents)
+        if object_type['name'] == 'Mutation'
+          next unless @options[:landing_pages][:mutation].nil?
+        end
+        if object_type['name'] == 'Query'
+          metadata = ''
+          unless @options[:landing_pages][:query].nil?
+            query_landing_page = @options[:landing_pages][:query]
+            query_landing_page = File.read(query_landing_page)
+            if @renderer.respond_to?(:has_yaml?) && \
+               @renderer.has_yaml?(query_landing_page) && \
+               @renderer.respond_to?(:yaml_split)
+              pieces = @renderer.yaml_split(query_landing_page)
+              pieces[2] = pieces[2].chomp
+              metadata = pieces[1, 3].join("\n")
+              query_landing_page = pieces[4]
+            end
+            object_type['description'] = query_landing_page
+          end
+          opts = default_generator_options(type: object_type)
+          contents = @graphql_object_template.result(OpenStruct.new(opts).instance_eval { binding })
+          write_file('static', 'query', metadata + contents)
+        else
+          opts = default_generator_options(type: object_type)
+          contents = @graphql_object_template.result(OpenStruct.new(opts).instance_eval { binding })
+          write_file('object', object_type['name'], contents)
+        end
       end
     end
 
@@ -131,6 +182,7 @@ def write_file(type, name, contents)
           path = @options[:output_dir]
         else
           path = File.join(@options[:output_dir], name)
+          FileUtils.mkdir_p(path)
         end
       else
         path = File.join(@options[:output_dir], type, name.downcase)
diff --git a/lib/graphql-docs/landing_pages/enum.md b/lib/graphql-docs/landing_pages/enum.md
@@ -0,0 +1,9 @@
+---
+title: Enums
+---
+
+# Enums
+
+Enums represent a possible set of values for a field. For example, the `Issue` object has a field called `state`. The state of an issue may be `OPEN` or `CLOSED`.
+
+For more information, see [the GraphQL spec](https://facebook.github.io/graphql/#sec-Enums).
diff --git a/lib/graphql-docs/landing_pages/index.md b/lib/graphql-docs/landing_pages/index.md
@@ -1,3 +1,7 @@
+---
+title: GraphQL documentation
+---
+
 # GraphQL Reference
 
 These docs were generated by [graphql-docs](https://github.com/gjtorikian/graphql-docs).
diff --git a/lib/graphql-docs/landing_pages/input_object.md b/lib/graphql-docs/landing_pages/input_object.md
@@ -0,0 +1,9 @@
+---
+title: Input Objects
+---
+
+# Input Objects
+
+Input objects are best described as "composable objects" in that they contain a set of input fields that define a particular object. For example, the `AuthorInput` takes a field called `emails`. Providing a value for `emails` will transform the `AuthorInput` into a list of `User` objects which contain that email address/
+
+For more information, see [the GraphQL spec](https://facebook.github.io/graphql/#sec-Input-Objects).
diff --git a/lib/graphql-docs/landing_pages/interface.md b/lib/graphql-docs/landing_pages/interface.md
@@ -0,0 +1,9 @@
+---
+title: Interfaces
+---
+
+# Interfaces
+
+GraphQL Interfaces are a sort of "parent object" from which other objects can "inherit" from. For example, `Stars` is considered an interface, because both `Repository` and `Gist` can be starred. An interface has its own list of named fields that are shared by implementing objects.
+
+For more information, see [the GraphQL spec](https://facebook.github.io/graphql/#sec-Interfaces).
diff --git a/lib/graphql-docs/landing_pages/mutation.md b/lib/graphql-docs/landing_pages/mutation.md
@@ -0,0 +1,11 @@
+---
+title: Mutations
+---
+
+# Mutations
+
+Every GraphQL schema has a root type for both queries and mutations.
+
+The mutation type defines how GraphQL operations change data. It is analogous to performing HTTP verbs such as `POST`, `PATCH`, and `DELETE`.
+
+For more information, see [the GraphQL spec](https://facebook.github.io/graphql/#sec-Type-System).
diff --git a/lib/graphql-docs/landing_pages/object.md b/lib/graphql-docs/landing_pages/object.md
@@ -0,0 +1,8 @@
+---
+title: Objects
+---
+# Objects
+
+Objects in GraphQL represent the resources that you can access. Objects can contain a list of fields, which are specifically typed. For example, the `Repository` object has a field called `name`, which is a `String`.
+
+For more information, see [the GraphQL spec](https://facebook.github.io/graphql/#sec-Objects).
diff --git a/lib/graphql-docs/landing_pages/query.md b/lib/graphql-docs/landing_pages/query.md
@@ -0,0 +1,4 @@
+---
+title: Queries
+---
+Every GraphQL schema has a root type for both queries and mutations. The [query type](https://facebook.github.io/graphql/#sec-Type-System) defines GraphQL operations that retrieve data from the server.
diff --git a/lib/graphql-docs/landing_pages/scalar.md b/lib/graphql-docs/landing_pages/scalar.md
@@ -0,0 +1,9 @@
+---
+title: Scalars
+---
+
+# Scalars
+
+Scalars are primitive values such as `Int` or `String`.
+
+For more information, see [the GraphQL spec](https://facebook.github.io/graphql/#sec-Scalars).
diff --git a/lib/graphql-docs/landing_pages/union.md b/lib/graphql-docs/landing_pages/union.md
@@ -0,0 +1,9 @@
+---
+title: Unions
+---
+
+# Unions
+
+A union is a type of object that can represent one of many kinds of objects. For example, a field marked as a `ReactableUnion` could be a `CommitComment`, an `Issue`, an `IssueComment`, or a `PullRequestReviewComment`, because each of those objects can be reacted on.
+
+For more information, see [the GraphQL spec](https://facebook.github.io/graphql/#sec-Unions).
diff --git a/lib/graphql-docs/layouts/default.html b/lib/graphql-docs/layouts/default.html
@@ -4,7 +4,7 @@
     <meta charset="utf-8">
     <meta name="description" content="<%= name %> GraphQL documentation">
     <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
-    <title><%= name %></title>
+    <title><%= title || name %></title>
     <link rel="stylesheet" href="<%= base_url %>/assets/style.css">
     <script src="https://cdnjs.cloudflare.com/ajax/libs/anchor-js/3.2.2/anchor.min.js"></script>
     <script>
diff --git a/lib/graphql-docs/layouts/graphql_enums.html b/lib/graphql-docs/layouts/graphql_enums.html
@@ -1,4 +1,4 @@
-## <%= type['name'] %>
+# <%= type['name'] %>
 
 <%= type['description'] %>
 
diff --git a/lib/graphql-docs/layouts/graphql_input_objects.html b/lib/graphql-docs/layouts/graphql_input_objects.html
@@ -1,4 +1,4 @@
-## <%= type['name'] %>
+# <%= type['name'] %>
 
 <%= type['description'] %>
 
diff --git a/lib/graphql-docs/layouts/graphql_interfaces.html b/lib/graphql-docs/layouts/graphql_interfaces.html
@@ -1,10 +1,10 @@
-## <%= type['name'] %>
+# <%= type['name'] %>
 
 <%= type['description'] %>
 
 <% unless type['fields'].empty? %>
 
-### Fields
+## Fields
 
 <%= include.('fields.html', fields: type['fields']) %>
 
diff --git a/lib/graphql-docs/layouts/graphql_mutations.html b/lib/graphql-docs/layouts/graphql_mutations.html
@@ -1,8 +1,8 @@
-## <%= type['name'] %>
+# <%= type['name'] %>
 
 <%= type['description'] %>
 
-## Input fields
+# Input fields
 
 <%= include.('/fields.html', fields: input_fields['inputFields']) %>
 
diff --git a/lib/graphql-docs/layouts/graphql_objects.html b/lib/graphql-docs/layouts/graphql_objects.html
@@ -1,10 +1,10 @@
-## <%= type['name'] %>
+# <%= type['name'] %>
 
 <%= type['description'] %>
 
 <% unless type['interfaces'].empty? %>
 
-### Implements
+## Implements
 
 <ul>
   <% type['interfaces'].each do |interface| %>
@@ -16,15 +16,15 @@
 
 <% unless type['connections'].empty? %>
 
-### Connections
+## Connections
 
 <%= include.('connections.html', connections: type['connections']) %>
 
 <% end %>
 
 <% unless type['fields'].empty? %>
 
-### Fields
+## Fields
 
 <%= include.('fields.html', fields: type['fields']) %>
 
diff --git a/lib/graphql-docs/layouts/graphql_scalars.html b/lib/graphql-docs/layouts/graphql_scalars.html
@@ -1,3 +1,3 @@
-## <%= type['name'] %>
+# <%= type['name'] %>
 
 <%= type['description'] %>
diff --git a/lib/graphql-docs/layouts/graphql_unions.html b/lib/graphql-docs/layouts/graphql_unions.html
@@ -1,4 +1,4 @@
-## <%= type['name'] %>
+# <%= type['name'] %>
 
 <%= type['description'] %>
 
diff --git a/lib/graphql-docs/layouts/includes/sidebar.html b/lib/graphql-docs/layouts/includes/sidebar.html
diff --git a/lib/graphql-docs/renderer.rb b/lib/graphql-docs/renderer.rb
diff --git a/test/graphql-docs/fixtures/landing_pages/broken_yaml.md b/test/graphql-docs/fixtures/landing_pages/broken_yaml.md
diff --git a/test/graphql-docs/generator_test.rb b/test/graphql-docs/generator_test.rb
diff --git a/test/graphql-docs/graphql-docs_test.rb b/test/graphql-docs/graphql-docs_test.rb
diff --git a/test/graphql-docs/renderer_test.rb b/test/graphql-docs/renderer_test.rb

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+# rubocop:disable Style/FileName`
`1`	`2`	`require 'graphql-docs/client'`
`2`	`3`	`require 'graphql-docs/helpers'`
`3`	`4`	`require 'graphql-docs/renderer'`