graphql-docs 1.0.0.pre1 → 1.0.0.pre2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2caa4bbf75cebf1a7829a2d840b9f0be679c202c
-  data.tar.gz: 31c198f0974c6cfa3d95bc4dd7c61f39b6510a05
+  metadata.gz: f9ace666d5ef2589da4991e236b929b2fd0ec58b
+  data.tar.gz: 5273fb7bf7bab9f9c5e9fbd36e92006822e1e18d
 SHA512:
-  metadata.gz: 83da234485764033976a3b9209a7f4a8f50cdc76b69977e8772d7ce06a1466b8983100c0498eba86e3157cd3660f89ef99ce56e0d285f511344faf1779da2f2a
-  data.tar.gz: 9b94daf15048375627bd7248e2a30a5a93542226eb0304c72ba13a5ab090d9d5898414637650f93f802bc4fea1a086e6003355fd100643372780cca391c05a3f
+  metadata.gz: ad3dd49c668b82de48707dd84905b4951ecfcbb16795c690eaccb4b74276fad4fa2140530becdb38045c351802e863bd9ff27509ddd497ee7f549b5c8d420d80
+  data.tar.gz: 98b5241afd6d9b9c0b8024a0bfcae9393b70cf51f88a50031ed3e812126bc8bd8e97d29c58c805eaa7672c664e664a8ac93b1b97ffbd25c6ef3a89c08b2f17b9

data/README.md

@@ -36,16 +36,15 @@ There are several phases going on the single `GraphQLDocs.build` call:
 
 * The GraphQL IDL file is read (if you passed `filename`) through `GraphQL::Client` (or simply read if you passed a string through `schema`).
 * `GraphQL::Parser` manipulates the IDL into a slightly saner format.
-* `GraphQL::Generator` takes that saner format and converts it into HTML.
-* `GraphQL::Renderer` technically runs as part of the generation phase. It passes the contents of each page through a Markdown renderer.
+* `GraphQL::Generator` takes that saner format and begins the process of applying items to the HTML templates.
+* `GraphQL::Renderer` technically runs as part of the generation phase. It passes the contents of each page and converts it into HTML.
 
 If you wanted to, you could break these calls up individually. For example:
 
 ``` ruby
 options = {}
 options[:filename] = "#{File.dirname(__FILE__)}/../data/graphql/schema.idl"
-my_renderer = MySuperCoolRenderer(options)
-options[:renderer] = my_renderer
+options[:renderer] = MySuperCoolRenderer
 
 options = GraphQLDocs::Configuration::GRAPHQLDOCS_DEFAULTS.merge(options)
 
@@ -63,17 +62,23 @@ generator.generate
 
 By default, the HTML generation process uses ERB to layout the content. There are a bunch of default options provided for you, but feel free to override any of these. The *Configuration* section below has more information on what you can change.
 
-It also uses [html-pipeline](https://github.com/jch/html-pipeline) to perform the Markdown rendering by default. You can override this by providing a custom rendering class. `initialize` takes two arguments, the configuration options and the parsed schema. You must implement at least one method, `render`, which takes the GraphQL type, the name, and the layout contents. For example:
+It also uses [html-pipeline](https://github.com/jch/html-pipeline) to perform the rendering by default. You can override this by providing a custom rendering class.You must implement two methods:
+
+* `initialize` - Takes two arguments, the parsed `schema` and the configuration `options`.
+* `render` Takes the contents of a template page. It also takes two optional kwargs, the GraphQL `type` and its `name`. For example:
 
 ``` ruby
 class CustomRenderer
-  def initialize(options, parsed_schema)
-    @options = options
+  def initialize(schema, options)
     @parsed_schema = parsed_schema
+    @options = options
   end
 
-  def render(type, name, contents)
-    contents.sub(/Repository/i, 'Meow Woof!')
+  def render(contents, type: nil, name: nil)
+    contents.sub(/Repository/i, '<strong>Meow Woof!</strong>')
+
+    opts[:content] = contents
+    @graphql_default_layout.result(OpenStruct.new(opts).instance_eval { binding })
   end
 end
 
@@ -83,13 +88,15 @@ options[:renderer] = CustomRenderer
 GraphQLDocs.build(options)
 ```
 
+If your `render` method returns `nil`, the `Generator` will not attempt to write any HTML file.
+
 ### Helper methods
 
 In your ERB layouts, there are several helper methods you can use. The helper methods are:
 
 * `slugify(str)` - This slugifies the given string.
 * `include(filename, opts)` - This embeds a template from your `includes` folder, passing along the local options provided.
-* `markdown(string)` - This converts a string from Markdown to HTML.
+* `markdownify(string)` - This converts a string into HTML via CommonMarker.
 * `graphql_operation_types`, `graphql_mutation_types`, `graphql_object_types`, `graphql_interface_types`, `graphql_enum_types`, `graphql_union_types`, `graphql_input_object_types`, `graphql_scalar_types` - Collections of the various GraphQL types.
 
 To call these methods within templates, you must use the dot notation, such as `<%= slugify.(text) %>`.
@@ -100,12 +107,8 @@ The following options are available:
 
 | Option | Description | Default |
 | :----- | :---------- | :------ |
-| `access_token` | Uses this token while making requests through `GraphQLDocs::Client`. | `nil` |
-| `headers` | Uses these headers while making requests through `GraphQLDocs::Client`. | `{}` |
-| `login` | Uses this login while making requests through `GraphQLDocs::Client`. | `nil` |
-| `password` | Uses this password while making requests through `GraphQLDocs::Client`. | `nil` |
-| `path` | `GraphQLDocs::Client` loads a JSON file found at this location, representing the response from an introspection query. | `nil` |
-| `url` | `GraphQLDocs::Client` makes a `POST` request to this URL, passing along the introspection query. | `nil` |
+| `filename` | The location of your schema's IDL file. | `nil` |
+| `schema` | A string representing a schema IDL file. | `nil` |
 | `output_dir` | The location of the output HTML. | `./output/` |
 | `use_default_styles` | Indicates if you want to use the default styles. | `true` |
 | `base_url` | Indicates the base URL to prepend for assets and links. | `""` |
@@ -114,7 +117,7 @@ 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 found 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/_.
 
 ## Development
 

data/lib/graphql-docs/generator.rb

@@ -11,7 +11,7 @@ module GraphQLDocs
       @parsed_schema = parsed_schema
       @options = options
 
-      @renderer = @options[:renderer].new(@options, @parsed_schema)
+      @renderer = @options[:renderer].new(@parsed_schema, @options)
 
       @graphql_operation_template = ERB.new(File.read(@options[:templates][:operation]))
       @graphql_object_template = ERB.new(File.read(@options[:templates][:objects]))
@@ -88,10 +88,8 @@ module GraphQLDocs
           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)
+            if has_yaml?(query_landing_page)
+              pieces = yaml_split(query_landing_page)
               pieces[2] = pieces[2].chomp
               metadata = pieces[1, 3].join("\n")
               query_landing_page = pieces[4]
@@ -108,6 +106,7 @@ module GraphQLDocs
     def create_graphql_object_pages
       graphql_object_types.each do |object_type|
         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
@@ -186,10 +185,43 @@ module GraphQLDocs
         FileUtils.mkdir_p(path)
       end
 
+      if has_yaml?(contents)
+        # Split data
+        meta, contents = split_into_metadata_and_contents(contents)
+        @options = @options.merge(meta)
+      end
+
       # normalize spacing so that CommonMarker doesn't treat it as `pre`
       contents.gsub!(/^\s*$/, '')
-      contents = @renderer.render(type, name, contents.gsub(/^\s{4}/m, '  '))
+      contents.gsub!(/^\s{4}/m, '  ')
+
+      contents = @renderer.render(contents, type: type, name: name)
       File.write(File.join(path, 'index.html'), contents) unless contents.nil?
     end
+
+    def split_into_metadata_and_contents(contents)
+      opts = {}
+      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]) || {}
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        raise "Could not parse YAML for #{name}: #{e.message}"
+      end
+      [meta, pieces[4]]
+    end
+
+    def has_yaml?(contents)
+      contents =~ /\A-{3,5}\s*$/
+    end
+
+    def yaml_split(contents)
+      contents.split(/^(-{5}|-{3})[ \t]*\r?\n?/, 3)
+    end
   end
 end

data/lib/graphql-docs/helpers.rb

@@ -1,5 +1,3 @@
-require 'commonmarker'
-
 module GraphQLDocs
   module Helpers
     SLUGIFY_PRETTY_REGEXP = Regexp.new("[^[:alnum:]._~!$&'()+,;=@]+").freeze
@@ -18,9 +16,9 @@ module GraphQLDocs
       template.result(OpenStruct.new(opts.merge(helper_methods)).instance_eval { binding })
     end
 
-    def markdown(string)
+    def markdownify(string)
       return '' if string.nil?
-      ::CommonMarker.render_html(string, :DEFAULT)
+      ::CommonMarker.render_html(string, :DEFAULT).strip
     end
 
     def graphql_operation_types
@@ -63,10 +61,8 @@ module GraphQLDocs
       return @templates[filename] unless @templates[filename].nil?
 
       contents = File.read(File.join(@options[:templates][:includes], filename))
-      # normalize spacing so that CommonMarker doesn't treat it as `pre`
-      template = contents.gsub(/^\s{4}/m, '  ')
-      @templates[filename] = ERB.new(template)
-      @templates[filename]
+
+      @templates[filename] = ERB.new(contents)
     end
 
     def helper_methods

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

@@ -2,18 +2,19 @@
 
 <%= type[:description] %>
 
+<% if !type[:input_fields].empty? %>
+
 <h2>Input fields</h2>
 
-<% if !type[:input_fields].empty? %>
-  <%= include.('/fields.html', fields: type[:input_fields]) %>
-<% else %>
-  <p>None</p>
+<%= include.('fields.html', fields: type[:input_fields]) %>
+
 <% end %>
 
-<h2>Return fields</h2>
 
 <% if !type[:return_fields].empty? %>
-  <%= include.('/fields.html', fields: type[:return_fields]) %>
-<% else %>
-  <p>None</p>
+
+<h2>Return fields</h2>
+
+<%= include.('fields.html', fields: type[:return_fields]) %>
+
 <% end %>

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

@@ -14,7 +14,7 @@
       <code><a href="<%= base_url %>/<%= argument[:type][:path]%>"><%= argument[:type][:info] %></a></code>
     </td>
     <td>
-      <p><%= markdown.(argument[:description]) %></p>
+      <p><%= markdownify.(argument[:description]) %></p>
     </td>
   </tr>
   <% end %>

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

@@ -6,11 +6,7 @@
   <div class="description-wrapper">
     <p><%= connection[:description] %></p>
 
-    <% unless connection[:arguments].empty? %>
-
-      <%= include.('arguments.html', args: connection[:arguments]) %>
-
-    <% end %>
+    <%= include.('arguments.html', args: connection[:arguments]) %>
   </div>
 </div>
 

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

@@ -1,25 +1,20 @@
 <% fields.each do |field| %>
 
 <div class="field-entry <%= classes[:field_entry] %>">
-  <% next if field[:name] == "id" || field[:name].blank? %>
-
   <span class="field-name"><%= field[:name] %> (<code><a href="<%= base_url %>/<%= field[:type][:path] %>"><%= field[:type][:info] %></a></code>)</span>
 
   <div class="description-wrapper">
   <% if field[:is_deprecated] %>
     <div class="deprecation-notice <%= classes[:deprecation_notice] %>">
       <span class="deprecation-title">Deprecation notice</span>
-      <%= markdown.(field[:deprecation_reason]) %>
+      <%= markdownify.(field[:deprecation_reason]) %>
     </div>
   <% end %>
 
-  <% if field[:description].present? %>
-    <%= markdown.(field[:description].strip) %>
-  <% end %>
+  <%= markdownify.(field[:description]) %>
+
+  <%= include.('arguments.html', args: field[:arguments]) %>
 
-  <% unless field[:arguments].blank? %>
-    <%= include.('arguments.html', args: field[:arguments]) %>
-  <% end %>
   </div>
 </div>
 

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

@@ -1,18 +1,12 @@
 <% input_fields.each do |field| %>
 
 <div class="field-entry <%= classes[:field_entry] %>">
-  <% next if field[:name] == "id" || field[:name].blank? %>
-
   <span class="field-name"><%= field[:name] %> (<a href="<%= base_url %>/<%= field[:type][:path] %>"><code><%= field[:type][:info] %></code></a>)</span>
 
   <div class="description-wrapper">
-    <p><%= field[:description] %></p>
-
-    <% unless field[:args].nil? %>
-
-      <%= include.('arguments.html', args: field[:args]) %>
+    <%= field[:description] %>
 
-    <% end %>
+    <%= include.('arguments.html', args: field[:args]) %>
   </div>
 </div>
 

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

@@ -8,7 +8,7 @@
     <% if value[:is_deprecated] %>
       <div class="deprecation-notice <%= classes[:deprecation_notice] %>">
         <span class="deprecation-title">Deprecation notice</span>
-        <%= markdown.(value[:deprecation_reason]) %>
+        <%= markdownify.(value[:deprecation_reason]) %>
       </div>
     <% end %>
 

data/lib/graphql-docs/parser.rb

@@ -141,8 +141,8 @@ module GraphQLDocs
 
         hash[:type] = generate_type(field.type)
 
+        hash[:arguments] = []
         if field.respond_to?(:arguments)
-          hash[:arguments] = []
           field.arguments.values.each do |arg|
             h = {}
             h[:name] = arg.name

data/lib/graphql-docs/renderer.rb

@@ -6,9 +6,9 @@ module GraphQLDocs
   class Renderer
     include Helpers
 
-    def initialize(options, parsed_schema)
-      @options = options
+    def initialize(parsed_schema, options)
       @parsed_schema = parsed_schema
+      @options = options
 
       unless @options[:templates][:default].nil?
         @graphql_default_layout = ERB.new(File.read(@options[:templates][:default]))
@@ -34,44 +34,18 @@ module GraphQLDocs
       @pipeline = HTML::Pipeline.new(filters, @pipeline_config[:context])
     end
 
-    def render(type, name, contents)
+    def render(contents, type: nil, name: nil)
       opts = { base_url: @options[:base_url] }.merge({ type: type, name: name}).merge(helper_methods)
 
-      if has_yaml?(contents)
-        # Split data
-        meta, contents = split_into_metadata_and_contents(contents)
-        opts = opts.merge(meta)
-      end
-
-      contents = @pipeline.to_html(contents)
+      contents = to_html(contents)
       return contents if @graphql_default_layout.nil?
       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
-
-    def split_into_metadata_and_contents(contents)
-      opts = {}
-      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]) || {}
-      rescue Exception => e # rubocop:disable Lint/RescueException
-        raise "Could not parse YAML for #{name}: #{e.message}"
-      end
-      [meta, pieces[4]]
+    def to_html(string)
+      return '' if string.nil?
+      CommonMarker.render_html(string, :DEFAULT).strip
     end
 
     private

data/lib/graphql-docs/version.rb

@@ -1,3 +1,3 @@
 module GraphQLDocs
-  VERSION = '1.0.0.pre1'
+  VERSION = '1.0.0.pre2'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: graphql-docs
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre1
+  version: 1.0.0.pre2
 platform: ruby
 authors:
 - Garen Torikian
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-09-13 00:00:00.000000000 Z
+date: 2017-09-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphql