graphql-docs 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: aa92319fbde2fb092c1060c9b754edbc7967dffb
-  data.tar.gz: 6559b9600700c459a582613b400e2fb52f7d0132
+  metadata.gz: '0779515b3313c00ee5bf7ba9a57592bd90a79d13'
+  data.tar.gz: 18b9ce93fc442cdf8c851dd0be0c6facf91f0d6e
 SHA512:
-  metadata.gz: 73fa9af50971492828db578ea7f9118fda68fcc54a6854c33ea55def59363c5140f55893334c2a4d98467fe7ca08f18b5d3e81dfaa1c55b8f75986480ed391b4
-  data.tar.gz: b1541dd0a1374b155612d737daf25a7ad0670d3f71363922199f012e72aab0a45d0b68eaeba2dda24a0111928b9bfb6ed8ac7b69ae8b0d98618933b90a3d336a
+  metadata.gz: 03dc4d16f2aa0c8000015a74a715429b8d8d4992fa8a3838d693d5d2bb90473435b3a22dadecb24642f6a620d8d53a35c37625021950a220278006f354051bb0
+  data.tar.gz: c5cb0870d13d1838fd199fd24da03cb84e88a6fe014fe251c17477e28e6910481182cd823a29edfa9d55fd091116fe36bd9ee4af9083ea73dba3db92942e915b

data/README.md

@@ -102,6 +102,7 @@ In your ERB layouts, there are several helper methods you can use. The helper me
 To call these methods within templates, you must use the dot notation, such as `<%= slugify.(text) %>`.
 
 For `markdownify`, `CommonMarker` is not enabled by default (because it relies on native code). You will need to add `require 'commonmarker'` if you wish to use it.
+
 ## Configuration
 
 The following options are available:
@@ -118,7 +119,57 @@ The following options are available:
 | `renderer` | The rendering class to use. | `GraphQLDocs::Renderer`
 | `templates` | The templates to use when generating HTML. You may override any of the following keys: `default`, `includes`, `operations`, `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 available in _lib/graphql-docs/configuration.rb/_.
+| `classes` | Additional class names you can provide to certain elements. | The full list is available in _lib/graphql-docs/configuration.rb_.
+| `notices` | A proc used to add notices to schema members. See *Customizing Notices* section below. | `nil` |
+
+### Customizing Notices
+
+A notice is a block of CommonMark text that optionally has a title which is displayed above a schema member's description. The
+look of a notice block can be controlled by specifying a custom class for it and then styled via CSS.
+
+The `notices` option allows you to customize the notices that appear for a specific schema member using a proc.
+
+The proc will be called for each schema member and needs to return an array of notices or an empty array if there are none.
+
+A `notice` has the following options:
+
+| Option | Description |
+| :----- | :---------- |
+| `body` | CommonMark body of the notice |
+| `title` | Optional title of the notice |
+| `class` | Optional CSS class for the wrapper `<div>` of the notice |
+| `title_class` | Optional CSS class for the `<span>` of the notice's title |
+
+Example of a `notices` proc that adds a notice to the `TeamDiscussion` type:
+
+```ruby
+options[:notice] = (schema_member_path) -> {
+  notices = []
+
+  if schema_member_path == "TeamDiscussion"
+    notices << {
+      class: "preview-notice",
+      body: "Available via the [Team Discussion](/previews/team-discussion) preview.",
+    }
+  end
+
+  notices
+}
+```
+
+The format of `schema_member_path` is a dot delimited path to the schema member. For example:
+
+```ruby
+"Author", # an object
+"ExtraInfo" # an interface,
+"Author.socialSecurityNumber" # a field
+"Book.author.includeMiddleInitial" # an argument
+"Likeable" # a union,
+"Cover" # an enum
+"Cover.DIGITAL" # an enum value
+"BookOrder" # an input object
+"Mutation.addLike" # a mutation
+```
 
 ## Development
 

data/lib/graphql-docs/configuration.rb

@@ -51,7 +51,9 @@ module GraphQLDocs
 
       classes: {
         field_entry: '',
-        deprecation_notice: ''
+        deprecation_notice: '',
+        notice: '',
+        notice_title: '',
       }
     }.freeze
   end

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

@@ -1,9 +1,7 @@
-# <%= type[:name] %>
+<h1><%= type[:name] %></h1>
 
-<%= type[:description] %>
+<%= include.('notices.html', notices: type[:notices]) %>
 
-<% unless type[:values].empty? %>
+<%= type[:description] %>
 
 <%= include.('values.html', values: type[:values]) %>
-
-<% end %>

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

@@ -1,5 +1,7 @@
 <h1><%= type[:name] %></h1>
 
+<%= include.('notices.html', notices: type[:notices]) %>
+
 <%= type[:description] %>
 
 <% unless type[:input_fields].nil? %>

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

@@ -1,5 +1,7 @@
 <h1><%= type[:name] %></h1>
 
+<%= include.('notices.html', notices: type[:notices]) %>
+
 <%= type[:description] %>
 
 <% unless type[:implemented_by].empty? %>

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

@@ -1,5 +1,7 @@
 <h1><%= type[:name] %></h1>
 
+<%= include.('notices.html', notices: type[:notices]) %>
+
 <%= type[:description] %>
 
 <% if !type[:input_fields].empty? %>

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

@@ -1,5 +1,7 @@
 <h1><%= type[:name] %></h1>
 
+<%= include.('notices.html', notices: type[:notices]) %>
+
 <%= type[:description] %>
 
 <% unless type[:interfaces].empty? %>

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

@@ -1,9 +1,7 @@
-# <%= type[:name] %>
+<h1><%= type[:name] %></h1>
 
-<%= type[:description] %>
+<%= include.('notices.html', notices: type[:notices]) %>
 
-<% unless type[:possible_types].empty? %>
+<%= type[:description] %>
 
 <%= include.('possible_types.html', possible_types: type[:possible_types]) %>
-
-<% end %>

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

@@ -4,6 +4,7 @@
   <span id="<%= slugify.(connection[:name]) %>" class="field-name connection-name"><%= connection[:name] %> (<a href="<%= base_url %>/<%= connection[:type][:path] %>"><code><%= connection[:type][:info] %></code></a>)</span>
 
   <div class="description-wrapper">
+    <%= include.('notices.html', notices: connection[:notices]) %>
     <p><%= connection[:description] %></p>
 
     <% unless connection[:arguments].empty? %>

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

@@ -11,6 +11,8 @@
     </div>
   <% end %>
 
+  <%= include.('notices.html', notices: field[:notices]) %>
+
   <%= markdownify.(field[:description]) %>
 
   <% unless field[:arguments].empty? %>

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

@@ -4,6 +4,8 @@
   <span id="<%= slugify.(field[:name]) %>" class="field-name"><%= field[:name] %> (<a href="<%= base_url %>/<%= field[:type][:path] %>"><code><%= field[:type][:info] %></code></a>)</span>
 
   <div class="description-wrapper">
+    <%= include.('notices.html', notices: field[:notices]) %>
+
     <%= field[:description] %>
 
     <% unless field[:arguments].empty? %>

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

@@ -0,0 +1,8 @@
+<% notices.each do |notice| %>
+  <div class="notice <%= classes[:notice] %> <%= notice[:class] %>">
+    <% if notice[:title] %>
+      <span class="notice-title <%= classes[:notice_title] %> <%= notice[:title_class] %>"><%= notice[:title] %></span>
+    <% end %>
+    <%= markdownify.(notice[:body]) %>
+  </div>
+<% end %>

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

@@ -5,6 +5,8 @@
   <h4 id="<%= slugify.(value[:name]) %>" class="name"><%= value[:name] %></h4>
 
   <div class="description-wrapper">
+    <%= include.('notices.html', notices: value[:notices]) %>
+
     <% if value[:is_deprecated] %>
       <div class="deprecation-notice <%= classes[:deprecation_notice] %>">
         <span class="deprecation-title">Deprecation notice</span>

data/lib/graphql-docs/parser.rb

@@ -8,6 +8,9 @@ module GraphQLDocs
 
     def initialize(schema, options)
       @options = options
+
+      @options[:notices] ||= -> (schema_member_path) { [] }
+
       @schema = GraphQL::Schema.from_definition(schema)
       @processed_schema = {
         operation_types: [],
@@ -25,6 +28,8 @@ module GraphQLDocs
       @schema.types.each_value do |object|
         data = {}
 
+        data[:notices] = @options[:notices].call(object.name)
+
         case object
         when ::GraphQL::ObjectType
           if object.name == 'Query'
@@ -32,7 +37,7 @@ module GraphQLDocs
             data[:description] = object.description
 
             data[:interfaces] = object.interfaces.map(&:name).sort
-            data[:fields], data[:connections] = fetch_fields(object.fields)
+            data[:fields], data[:connections] = fetch_fields(object.fields, object.name)
 
             @processed_schema[:operation_types] << data
           elsif object.name == 'Mutation'
@@ -43,15 +48,17 @@ module GraphQLDocs
 
             object.fields.each_value do |mutation|
               h = {}
+
+              h[:notices] = @options[:notices].call([object.name, mutation.name].join('.'))
               h[:name] = mutation.name
               h[:description] = mutation.description
-              h[:input_fields], _ = fetch_fields(mutation.arguments)
+              h[:input_fields], _ = fetch_fields(mutation.arguments, [object.name, mutation.name].join('.'))
 
               return_type = mutation.type
               if return_type.unwrap.respond_to?(:fields)
-                h[:return_fields], _ = fetch_fields(return_type.unwrap.fields)
+                h[:return_fields], _ = fetch_fields(return_type.unwrap.fields, return_type.name)
               else # it is a scalar return type
-                h[:return_fields], _ = fetch_fields({ "#{return_type.name}" => mutation })
+                h[:return_fields], _ = fetch_fields({ "#{return_type.name}" => mutation }, return_type.name)
               end
 
               @processed_schema[:mutation_types] << h
@@ -61,14 +68,14 @@ module GraphQLDocs
             data[:description] = object.description
 
             data[:interfaces] = object.interfaces.map(&:name).sort
-            data[:fields], data[:connections] = fetch_fields(object.fields)
+            data[:fields], data[:connections] = fetch_fields(object.fields, object.name)
 
             @processed_schema[:object_types] << data
           end
         when ::GraphQL::InterfaceType
           data[:name] = object.name
           data[:description] = object.description
-          data[:fields], data[:connections] = fetch_fields(object.fields)
+          data[:fields], data[:connections] = fetch_fields(object.fields, object.name)
 
           @processed_schema[:interface_types] << data
         when ::GraphQL::EnumType
@@ -77,6 +84,7 @@ module GraphQLDocs
 
           data[:values] = object.values.values.map do |val|
             h = {}
+            h[:notices] = @options[:notices].call([object.name, val.name].join('.'))
             h[:name] = val.name
             h[:description] = val.description
             unless val.deprecation_reason.nil?
@@ -97,7 +105,7 @@ module GraphQLDocs
           data[:name] = object.name
           data[:description] = object.description
 
-          data[:input_fields], _ = fetch_fields(object.input_fields)
+          data[:input_fields], _ = fetch_fields(object.input_fields, object.name)
 
           @processed_schema[:input_object_types] << data
         when ::GraphQL::ScalarType
@@ -132,13 +140,14 @@ module GraphQLDocs
 
     private
 
-    def fetch_fields(object_fields)
+    def fetch_fields(object_fields, parent_path)
       fields = []
       connections = []
 
       object_fields.each_value do |field|
         hash = {}
 
+        hash[:notices] = @options[:notices].call([parent_path, field.name].join('.'))
         hash[:name] = field.name
         hash[:description] = field.description
         if field.respond_to?(:deprecation_reason) && !field.deprecation_reason.nil?

data/lib/graphql-docs/version.rb

@@ -1,3 +1,3 @@
 module GraphQLDocs
-  VERSION = '1.2.0'
+  VERSION = '1.3.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: graphql-docs
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Garen Torikian
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-02-08 00:00:00.000000000 Z
+date: 2018-02-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphql
@@ -280,6 +280,7 @@ files:
 - lib/graphql-docs/layouts/includes/connections.html
 - lib/graphql-docs/layouts/includes/fields.html
 - lib/graphql-docs/layouts/includes/input_fields.html
+- lib/graphql-docs/layouts/includes/notices.html
 - lib/graphql-docs/layouts/includes/possible_types.html
 - lib/graphql-docs/layouts/includes/sidebar.html
 - lib/graphql-docs/layouts/includes/values.html