graphql-docs 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c4d60df082629a2051e1f56910ae53e15ac0c2f4
-  data.tar.gz: abde3dbad6ce9687c95a31d2312fb98fedff8067
+  metadata.gz: 57b3bab2a270f24272f4dbd5f01e35b4ca808c69
+  data.tar.gz: 40b5d99232276274abc5f96fd0cf3e6a3744ffe1
 SHA512:
-  metadata.gz: 8b97023604cff348beee6cbb17fd5175879232d7ac7fdae05711d0ff3cf0e640e97a2a2b78954ec1a4624cdda2ed47e4f183381b6cc21e2badf3065e8db575d4
-  data.tar.gz: c85ba82b15abdd9f46852e19b96e56e4324ccf28b1c2671be7eb65b5017642458003d88767179c07e21e861342ba345feb478596e9b2f224488bbe9b5e285d36
+  metadata.gz: 44dbb949bd168632077b04c060766740929309f04353730d165518241633b5f5f814b01935ad854a1fd1307e4950936b0f054b6be388a96c58c827efd3f15d77
+  data.tar.gz: acc2174c4f16ec02f995185c70817e337db9c045b57f9cc91a85c84036f9d1d7cc33692e49d5f2ff2811dec3c5aed6152c66bbf72a7e48d1e99bef1b8772c540

data/.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

data/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

data/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'

data/lib/graphql-docs.rb

@@ -1,3 +1,4 @@
+# rubocop:disable Style/FileName
 require 'graphql-docs/client'
 require 'graphql-docs/helpers'
 require 'graphql-docs/renderer'

data/lib/graphql-docs/configuration.rb

@@ -36,8 +36,18 @@ module GraphQLDocs
         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: {

data/lib/graphql-docs/generator.rb

@@ -33,8 +33,36 @@ module GraphQLDocs
       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 @@ module GraphQLDocs
     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 @@ module GraphQLDocs
           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)

data/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).

data/lib/graphql-docs/{layouts → 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).

data/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).

data/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).

data/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).

data/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).

data/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.

data/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).

data/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).

data/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>

data/lib/graphql-docs/layouts/graphql_enums.html

@@ -1,4 +1,4 @@
-## <%= type['name'] %>
+# <%= type['name'] %>
 
 <%= type['description'] %>
 

data/lib/graphql-docs/layouts/graphql_input_objects.html

@@ -1,4 +1,4 @@
-## <%= type['name'] %>
+# <%= type['name'] %>
 
 <%= type['description'] %>
 

data/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']) %>
 

data/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']) %>
 

data/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,7 +16,7 @@
 
 <% unless type['connections'].empty? %>
 
-### Connections
+## Connections
 
 <%= include.('connections.html', connections: type['connections']) %>
 
@@ -24,7 +24,7 @@
 
 <% unless type['fields'].empty? %>
 
-### Fields
+## Fields
 
 <%= include.('fields.html', fields: type['fields']) %>
 

data/lib/graphql-docs/layouts/graphql_scalars.html

@@ -1,3 +1,3 @@
-## <%= type['name'] %>
+# <%= type['name'] %>
 
 <%= type['description'] %>

data/lib/graphql-docs/layouts/graphql_unions.html

@@ -1,4 +1,4 @@
-## <%= type['name'] %>
+# <%= type['name'] %>
 
 <%= type['description'] %>
 

data/lib/graphql-docs/layouts/includes/sidebar.html

@@ -10,12 +10,12 @@
     <p>Queries</p>
     <ul class="menu-root">
       <li>
-        <a href="<%= base_url %>/object/query/" class="sidebar-link<% if title == "Query" %> current<% end %>">
-          RootQuery
+        <a href="<%= base_url %>/query/" class="sidebar-link<% if title == "Query" %> current<% end %>">
+          Query
         </a>
       </li>
       <li>
-        <a href="<%= base_url %>/object/mutation" class="sidebar-link<% if title == "Mutation" %> current<% end %>">
+        <a href="<%= base_url %>/mutation" class="sidebar-link<% if title == "Mutation" %> current<% end %>">
           Mutation
         </a>
       </li>
@@ -23,7 +23,7 @@
   </li>
 
   <li>
-    <p>Objects</p>
+    <p><a href="<%= base_url %>/object">Objects</a></p>
     <ul class="menu-root">
       <% graphql_object_types.().each do |type| %>
         <% @name = type["name"] %>
@@ -32,13 +32,18 @@
           <% next %>
         <% end %>
 
+        <!-- skip mutation stuff -->
+        <% if @name == "Mutation" || @name.end_with?("Payload") %>
+          <% next %>
+        <% end %>
+
         <!-- skip metadata stuff -->
         <% if @name.start_with?("__") %>
           <% next %>
         <% end %>
 
         <!-- skip root query stuff -->
-        <% if @name == "RootQuery" %>
+        <% if @name == "Query" %>
           <% next %>
         <% end %>
 
@@ -52,7 +57,25 @@
   </li>
 
   <li>
-    <p>Interfaces</p>
+    <p><a href="<%= base_url %>/mutation">Mutations</a></p>
+    <ul class="menu-root">
+      <% graphql_mutation_types.().each do |type| %>
+      <% @name = type["name"] %>
+      <!-- skip metadata stuff -->
+      <% if @name.start_with?("__") %>
+        <% next %>
+      <% end %>
+      <li>
+        <a href="<%= base_url %>/mutation/<%= @name.downcase %>/" class="sidebar-link<% if title == @name %> current<% end %>">
+          <%= @name %>
+        </a>
+      </li>
+      <% end %>
+    </ul>
+  </li>
+
+  <li>
+    <p><a href="<%= base_url %>/interface">Interfaces</a></p>
     <ul class="menu-root">
       <% graphql_interface_types.().each do |type| %>
         <% @name = type["name"] %>
@@ -66,7 +89,7 @@
   </li>
 
   <li>
-    <p>Enums</p>
+    <p><a href="<%= base_url %>/enum">Enums</a></p>
     <ul class="menu-root">
       <% graphql_enum_types.().each do |type| %>
       <% @name = type["name"] %>
@@ -84,7 +107,7 @@
   </li>
 
   <li>
-    <p>Unions</p>
+    <p><a href="<%= base_url %>/union">Unions</a></p>
     <ul class="menu-root">
       <% graphql_union_types.().each do |type| %>
       <% @name = type["name"] %>
@@ -98,7 +121,7 @@
   </li>
 
   <li>
-    <p>Input Objects</p>
+    <p><a href="<%= base_url %>/input_object">Input Objects</a></p>
     <ul class="menu-root">
       <% graphql_input_object_types.().each do |type| %>
       <% @name = type["name"] %>
@@ -112,7 +135,7 @@
   </li>
 
   <li>
-    <p>Scalars</p>
+    <p><a href="<%= base_url %>/scalar">Scalars</a></p>
     <ul class="menu-root">
       <% graphql_scalar_types.().each do |type| %>
       <% @name = type["name"] %>

data/lib/graphql-docs/renderer.rb

@@ -1,4 +1,5 @@
 require 'html/pipeline'
+require 'yaml'
 require 'extended-markdown-filter'
 
 module GraphQLDocs
@@ -34,12 +35,40 @@ module GraphQLDocs
     end
 
     def render(type, name, contents)
+      opts = { base_url: @options[:base_url] }.merge({ type: type, name: name}).merge(helper_methods)
+
+      if has_yaml?(contents)
+        # Split data
+        pieces = yaml_split(contents)
+        if pieces.size < 4
+          raise RuntimeError.new(
+            "The file '#{content_filename}' appears to start with a metadata section (three or five dashes at the top) but it does not seem to be in the correct format.",
+          )
+        end
+        # Parse
+        begin
+          meta = YAML.load(pieces[2]) || {}
+          opts = opts.merge(meta)
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          raise "Could not parse YAML for #{name}: #{e.message}"
+        end
+        contents = pieces[4]
+      end
+
       contents = @pipeline.to_html(contents)
       return contents if @graphql_default_layout.nil?
-      opts = { base_url: @options[:base_url] }.merge({ contents: contents, type: type, name: name}).merge(helper_methods)
+      opts[:content] = contents
       @graphql_default_layout.result(OpenStruct.new(opts).instance_eval { binding })
     end
 
+    def has_yaml?(contents)
+      contents =~ /\A-{3,5}\s*$/
+    end
+
+    def yaml_split(contents)
+      contents.split(/^(-{5}|-{3})[ \t]*\r?\n?/, 3)
+    end
+
     private
 
     def filter_key(s)

data/lib/graphql-docs/version.rb

@@ -1,3 +1,3 @@
 module GraphQLDocs
-  VERSION = '0.4.1'
+  VERSION = '0.5.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: graphql-docs
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Garen Torikian
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-05-09 00:00:00.000000000 Z
+date: 2017-05-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -254,6 +254,15 @@ files:
 - lib/graphql-docs/configuration.rb
 - lib/graphql-docs/generator.rb
 - lib/graphql-docs/helpers.rb
+- lib/graphql-docs/landing_pages/enum.md
+- lib/graphql-docs/landing_pages/index.md
+- lib/graphql-docs/landing_pages/input_object.md
+- lib/graphql-docs/landing_pages/interface.md
+- lib/graphql-docs/landing_pages/mutation.md
+- lib/graphql-docs/landing_pages/object.md
+- lib/graphql-docs/landing_pages/query.md
+- lib/graphql-docs/landing_pages/scalar.md
+- lib/graphql-docs/landing_pages/union.md
 - lib/graphql-docs/layouts/assets/_sass/_api-box.scss
 - lib/graphql-docs/layouts/assets/_sass/_content.scss
 - lib/graphql-docs/layouts/assets/_sass/_fonts.scss
@@ -302,7 +311,6 @@ files:
 - lib/graphql-docs/layouts/includes/possible_types.html
 - lib/graphql-docs/layouts/includes/sidebar.html
 - lib/graphql-docs/layouts/includes/values.html
-- lib/graphql-docs/layouts/index.md
 - lib/graphql-docs/parser.rb
 - lib/graphql-docs/renderer.rb
 - lib/graphql-docs/version.rb