graphql-docs 0.6.2 → 1.0.0.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c2ecb384368186912ae4330f6d725e143e00ce45
-  data.tar.gz: 37f6ff42e7f5c62eb036de963aae0f2f1d743a50
+  metadata.gz: d57299436da71122f707b8566d5c3866817206c9
+  data.tar.gz: f3d9e7e6c3f01a7720211bcbee87d1a26da2bb9c
 SHA512:
-  metadata.gz: 2dc4a7f5d016cae84c3017d5ef90c3c5c64a4273e6b7105f68cc3ff108537fc9f9222ce1da662da2de0cc638c0e313ee6fb706ab1091f9889a2f7a1f7090de8f
-  data.tar.gz: 5b707908d83d74f848e5efcc155d1fea2f2efce5607284b416e222cbdbde8472420ae6f4c966afa025368fdc793e4c2f38f96da806e5c43b3c839f98dc5ddcbd
+  metadata.gz: d77c30246e5dfe9a3a54243e08549b73e8b32ad933d78a39da04db84a69a8869fc074dfbcc677b1bd438792732d2f08fb1c7b9058593ac227ed340fde0d87975
+  data.tar.gz: c9b376846e30727006fb5282061e105ae9c28cf5f3659aec7389444cba5b87e4b28b92f1e7437c70996265b6c4d23c80198dae4518a113cf72ba9389bb519711

data/README.md

@@ -22,56 +22,34 @@ Or install it yourself as:
 
 ## Usage
 
-Simple! Call `GraphQLDocs.generate`, taking care to pass in the GraphQL endpoint:
-
-``` ruby
-GraphQLDocs.build(url: 'http://graphql.org/swapi-graphql/')
-```
-
-If your GraphQL endpoint requires authentication, you can provide a username or password, or an access token:
-
 ``` ruby
-options = {
-  url: 'http://graphql.org/swapi-graphql/'
-  login: 'gjtorikian',
-  password: 'lolnowai'
-}
-GraphQLDocs.build(options)
+# pass in a filename
+GraphQLDocs.build(filename: filename)
 
-options = {
-  url: 'http://graphql.org/swapi-graphql/'
-  access_token: 'something123'
-}
-
-GraphQLDocs.build(options)
-```
-
-If you already have the JSON locally, great! Call the same method with `path` instead:
-
-``` ruby
-GraphQLDocs.build(path: 'location/to/sw-api.json')
+# or pass in a string
+GraphQLDocs.build(schema: contents)
 ```
 
 ## Breakdown
 
-There are several phases going on in one little `GraphQLDocs.build` call:
+There are several phases going on the single `GraphQLDocs.build` call:
 
-* The GraphQL JSON is _fetched_ (if you passed `url`) through `GraphQL::Client` (or simply read if you passed `path`).
-* `GraphQL::Parser` manipulates that JSON into a slightly saner format.
-* `GraphQL::Generator` takes that JSON and converts it into HTML.
+* 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.
 
 If you wanted to, you could break these calls up individually. For example:
 
 ``` ruby
 options = {}
-options[:path] = "#{File.dirname(__FILE__)}/../data/graphql/docs.json"
+options[:filename] = "#{File.dirname(__FILE__)}/../data/graphql/schema.idl"
 my_renderer = MySuperCoolRenderer(options)
 options[:renderer] = my_renderer
 
 options = GraphQLDocs::Configuration::GRAPHQLDOCS_DEFAULTS.merge(options)
 
-response = File.read(options[:path])
+response = File.read(options[:filename])
 
 parser = GraphQLDocs::Parser.new(response, options)
 parsed_schema = parser.parse
@@ -99,7 +77,7 @@ class CustomRenderer
   end
 end
 
-options[:path] = 'location/to/sw-api.json'
+options[:filename] = 'location/to/sw-api.graphql'
 options[:renderer] = CustomRenderer
 
 GraphQLDocs.build(options)
@@ -112,8 +90,7 @@ In your ERB layouts, there are several helper methods you can use. The helper me
 * `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.
-* `format_type(field)` - This formats a type into an IDL-like representation. For example: `!Blah` or `[!Foo]`.
-* `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.
+* `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) %>`.
 
@@ -131,11 +108,11 @@ The following options are available:
 | `url` | `GraphQLDocs::Client` makes a `POST` request to this URL, passing along the introspection query. | `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. | `true` |
+| `base_url` | Indicates the base URL to prepend for assets and links. | `""` |
 | `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: `default`, `includes`, `objects`, `mutations`, `interfaces`, `enums`, `unions`, `input_objects`, `scalars`. | 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`, `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/_.
 

data/Rakefile

@@ -8,11 +8,23 @@ RuboCop::RakeTask.new(:rubocop)
 Rake::TestTask.new(:test) do |t|
   t.libs << 'test'
   t.libs << 'lib'
+  t.warning = false
   t.test_files = FileList['test/**/*_test.rb']
 end
 
 task default: :test
 
+Rake::Task[:test].enhance { Rake::Task[:html_proofer].invoke }
+
+desc 'Invoke HTML-Proofer'
+task html_proofer: [:generate_sample] do
+  require 'html-proofer'
+  output_dir = File.join(File.dirname(__FILE__), 'output')
+
+  proofer_options = { disable_external: true, assume_extension: true }
+  HTMLProofer.check_directory(output_dir, proofer_options).run
+end
+
 desc 'Set up a console'
 task :console do
   require 'pry'
@@ -28,13 +40,13 @@ task :console do
 end
 
 desc 'Generate the documentation'
-task :generate_sample, [:base_url] do |task, args|
+task :generate_sample do
+  require 'pry'
   require 'graphql-docs'
 
   options = {}
   options[:delete_output] = true
-  options[:base_url] = args.base_url || ''
-  options[:path] = File.join(File.dirname(__FILE__), 'test', 'graphql-docs', 'fixtures', 'gh-api.json')
+  options[:filename] = File.join(File.dirname(__FILE__), 'test', 'graphql-docs', 'fixtures', 'gh-schema.graphql')
 
   GraphQLDocs.build(options)
 end

data/graphql-docs.gemspec

@@ -20,7 +20,6 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'faraday', '< 0.10'#'~> 0.9'
   spec.add_dependency 'graphql', '~> 1.4'
 
   # rendering

data/lib/graphql-docs.rb

@@ -1,5 +1,4 @@
 # rubocop:disable Style/FileName
-require 'graphql-docs/client'
 require 'graphql-docs/helpers'
 require 'graphql-docs/renderer'
 require 'graphql-docs/configuration'
@@ -9,6 +8,7 @@ require 'graphql-docs/version'
 
 begin
   require 'awesome_print'
+  require 'pry'
 rescue LoadError; end
 
 module GraphQLDocs
@@ -16,22 +16,36 @@ module GraphQLDocs
     def build(options)
       options = GraphQLDocs::Configuration::GRAPHQLDOCS_DEFAULTS.merge(options)
 
-      if options[:url].nil? && options[:path].nil?
-        fail ArgumentError, 'No :url or :path provided!'
+      filename = options[:filename]
+      schema = options[:schema]
+
+      if !filename.nil? && !schema.nil?
+        raise ArgumentError, 'Pass in `filename` or `schema`, but not both!'
       end
 
-      if !options[:url].nil? && !options[:path].nil?
-        fail ArgumentError, 'You can\'t pass both :url and :path!'
+      if filename.nil? && schema.nil?
+        raise ArgumentError, 'Pass in either `filename` or `schema`'
       end
 
-      if options[:url]
-        client = GraphQLDocs::Client.new(options)
-        response = client.fetch
+      if filename
+        unless filename.is_a?(String)
+          raise TypeError, "Expected `String`, got `#{filename.class}`"
+        end
+
+        unless File.exist?(filename)
+          raise ArgumentError, "#{filename} does not exist!"
+        end
+
+        schema = File.read(filename)
       else
-        response = File.read(options[:path])
+        unless schema.is_a?(String)
+          raise TypeError, "Expected `String`, got `#{schema.class}`"
+        end
+
+        schema = schema
       end
 
-      parser = GraphQLDocs::Parser.new(response, options)
+      parser = GraphQLDocs::Parser.new(schema, options)
       parsed_schema = parser.parse
 
       generator = GraphQLDocs::Generator.new(parsed_schema, options)

data/lib/graphql-docs/configuration.rb

@@ -1,13 +1,9 @@
 module GraphQLDocs
   module Configuration
     GRAPHQLDOCS_DEFAULTS = {
-      # Client
-      access_token: nil,
-      headers: {},
-      login: nil,
-      password: nil,
-      path: nil,
-      url: nil,
+      # initialize
+      filename: nil,
+      schema: nil,
 
       # Generating
       delete_output: false,
@@ -30,6 +26,8 @@ module GraphQLDocs
         default: "#{File.dirname(__FILE__)}/layouts/default.html",
 
         includes: "#{File.dirname(__FILE__)}/layouts/includes",
+
+        operation: "#{File.dirname(__FILE__)}/layouts/graphql_operation.html",
         objects: "#{File.dirname(__FILE__)}/layouts/graphql_objects.html",
         mutations: "#{File.dirname(__FILE__)}/layouts/graphql_mutations.html",
         interfaces: "#{File.dirname(__FILE__)}/layouts/graphql_interfaces.html",

data/lib/graphql-docs/generator.rb

@@ -13,6 +13,7 @@ module GraphQLDocs
 
       @renderer = @options[:renderer].new(@options, @parsed_schema)
 
+      @graphql_operation_template = ERB.new(File.read(@options[:templates][:operation]))
       @graphql_object_template = ERB.new(File.read(@options[:templates][:objects]))
       @graphql_mutations_template = ERB.new(File.read(@options[:templates][:mutations]))
       @graphql_interfaces_template = ERB.new(File.read(@options[:templates][:interfaces]))
@@ -25,6 +26,7 @@ module GraphQLDocs
     def generate
       FileUtils.rm_rf(@options[:output_dir]) if @options[:delete_output]
 
+      create_graphql_operation_pages
       create_graphql_object_pages
       create_graphql_mutation_pages
       create_graphql_interface_pages
@@ -42,7 +44,7 @@ module GraphQLDocs
       end
 
       unless @options[:landing_pages][:mutation].nil?
-        write_file('static', 'mutation', File.read(@options[:landing_pages][:mutation]))
+        write_file('operation', 'mutation', File.read(@options[:landing_pages][:mutation]))
       end
 
       unless @options[:landing_pages][:interface].nil?
@@ -79,14 +81,10 @@ module GraphQLDocs
       true
     end
 
-    def create_graphql_object_pages
-      graphql_object_types.each do |object_type|
-        next if object_type['name'].start_with?('__')
-        if object_type['name'] == 'Mutation'
-          next unless @options[:landing_pages][:mutation].nil?
-        end
-        if object_type['name'] == 'Query'
-          metadata = ''
+    def create_graphql_operation_pages
+      graphql_operation_types.each do |query_type|
+        metadata = ''
+        if query_type[:name] == 'Query'
           unless @options[:landing_pages][:query].nil?
             query_landing_page = @options[:landing_pages][:query]
             query_landing_page = File.read(query_landing_page)
@@ -98,75 +96,74 @@ module GraphQLDocs
               metadata = pieces[1, 3].join("\n")
               query_landing_page = pieces[4]
             end
-            object_type['description'] = query_landing_page
+            query_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)
+          opts = default_generator_options(type: query_type)
+          contents = @graphql_operation_template.result(OpenStruct.new(opts).instance_eval { binding })
+          write_file('operation', query_type[:name], metadata + contents)
         end
       end
     end
 
+    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
+    end
+
     def create_graphql_mutation_pages
       graphql_mutation_types.each do |mutation|
-        input_name = mutation['args'].first['type']['ofType']['name']
-        return_name = mutation['type']['name']
-        input = graphql_input_object_types.find { |t| t['name'] == input_name }
-        payload = graphql_object_types.find { |t| t['name'] == return_name }
-
-        opts = default_generator_options({ type: mutation, input_fields: input, return_fields: payload })
+        opts = default_generator_options(type: mutation)
 
         contents = @graphql_mutations_template.result(OpenStruct.new(opts).instance_eval { binding })
-        write_file('mutation', mutation['name'], contents)
+        write_file('mutation', mutation[:name], contents)
       end
     end
 
     def create_graphql_interface_pages
       graphql_interface_types.each do |interface_type|
-        opts = default_generator_options({ type: interface_type })
+        opts = default_generator_options(type: interface_type)
 
         contents = @graphql_interfaces_template.result(OpenStruct.new(opts).instance_eval { binding })
-        write_file('interface', interface_type['name'], contents)
+        write_file('interface', interface_type[:name], contents)
       end
     end
 
     def create_graphql_enum_pages
       graphql_enum_types.each do |enum_type|
-        opts = default_generator_options({ type: enum_type })
+        opts = default_generator_options(type: enum_type)
 
         contents = @graphql_enums_template.result(OpenStruct.new(opts).instance_eval { binding })
-        write_file('enum', enum_type['name'], contents)
+        write_file('enum', enum_type[:name], contents)
       end
     end
 
     def create_graphql_union_pages
       graphql_union_types.each do |union_type|
-        opts = default_generator_options({ type: union_type })
+        opts = default_generator_options(type: union_type)
 
         contents = @graphql_unions_template.result(OpenStruct.new(opts).instance_eval { binding })
-        write_file('union', union_type['name'], contents)
+        write_file('union', union_type[:name], contents)
       end
     end
 
     def create_graphql_input_object_pages
       graphql_input_object_types.each do |input_object_type|
-        opts = default_generator_options({ type: input_object_type })
+        opts = default_generator_options(type: input_object_type)
 
         contents = @graphql_input_objects_template.result(OpenStruct.new(opts).instance_eval { binding })
-        write_file('input_object', input_object_type['name'], contents)
+        write_file('input_object', input_object_type[:name], contents)
       end
     end
 
     def create_graphql_scalar_pages
       graphql_scalar_types.each do |scalar_type|
-        opts = default_generator_options({ type: scalar_type })
+        opts = default_generator_options(type: scalar_type)
 
         contents = @graphql_scalars_template.result(OpenStruct.new(opts).instance_eval { binding })
-        write_file('scalar', scalar_type['name'], contents)
+        write_file('scalar', scalar_type[:name], contents)
       end
     end
 

data/lib/graphql-docs/helpers.rb

@@ -1,3 +1,5 @@
+require 'commonmarker'
+
 module GraphQLDocs
   module Helpers
     SLUGIFY_PRETTY_REGEXP = Regexp.new("[^[:alnum:]._~!$&'()+,;=@]+").freeze
@@ -18,92 +20,39 @@ module GraphQLDocs
 
     def markdown(string)
       return '' if string.nil?
-      CommonMarker.render_html(string, :DEFAULT)
+      ::CommonMarker.render_html(string, :DEFAULT)
     end
 
-    # Do you think I am proud of this? I am not.
-    def format_type(field)
-      type_path = name_slug = nil
-      type_name = ''
-
-      if field['type']['kind'] == 'NON_NULL'
-        if !field['type']['ofType']['ofType'].nil?
-          # we're going to be a list...but what kind?!
-          type_name << '['
-          if !field['type']['ofType']['ofType']['ofType'].nil?
-            type_path = field['type']['ofType']['ofType']['ofType']['kind']
-            type_name << field['type']['ofType']['ofType']['ofType']['name']
-            name_slug = field['type']['ofType']['ofType']['ofType']['name']
-            # A required list of required items: [Blah!]!
-            if field['type']['ofType']['ofType']['kind'] == 'NON_NULL'
-              type_name << '!'
-            end
-          else
-            # A required list of non-required items: [Blah]!
-            type_path = field['type']['ofType']['ofType']['kind']
-            type_name << field['type']['ofType']['ofType']['name']
-            name_slug = field['type']['ofType']['ofType']['name']
-          end
-          type_name << ']'
-          type_name << '!'
-        else
-          type_path = field['type']['ofType']['kind']
-          type_name << field['type']['ofType']['name']
-          name_slug = field['type']['ofType']['name']
-          # Simple non-null item: Blah!
-          type_name << '!'
-        end
-      elsif field['type']['kind'] == 'LIST'
-        type_name << '['
-        if field['type']['ofType']['kind'] == 'NON_NULL'
-          type_path = field['type']['ofType']['ofType']['kind']
-          type_name << field['type']['ofType']['ofType']['name']
-          name_slug = field['type']['ofType']['ofType']['name']
-          # Nullable list of non-null items: [Blah!]
-          type_name << '!'
-        else
-          # Nullable list of nullable items: [Blah]
-          type_path = field['type']['ofType']['kind']
-          type_name << field['type']['ofType']['name']
-          name_slug = field['type']['ofType']['name']
-        end
-        type_name << ']'
-      else
-        # Simple nullable item: Blah
-        type_path = field['type']['kind']
-        type_name << field['type']['name']
-        name_slug = field['type']['name']
-      end
-
-      [type_path.downcase, type_name, name_slug.downcase]
+    def graphql_operation_types
+      @parsed_schema[:operation_types] || []
     end
 
     def graphql_mutation_types
-      @parsed_schema['mutation_types'] || []
+      @parsed_schema[:mutation_types] || []
     end
 
     def graphql_object_types
-      @parsed_schema['object_types'] || []
+      @parsed_schema[:object_types] || []
     end
 
     def graphql_interface_types
-      @parsed_schema['interface_types'] || []
+      @parsed_schema[:interface_types] || []
     end
 
     def graphql_enum_types
-      @parsed_schema['enum_types'] || []
+      @parsed_schema[:enum_types] || []
     end
 
     def graphql_union_types
-      @parsed_schema['union_types'] || []
+      @parsed_schema[:union_types] || []
     end
 
     def graphql_input_object_types
-      @parsed_schema['input_object_types'] || []
+      @parsed_schema[:input_object_types] || []
     end
 
     def graphql_scalar_types
-      @parsed_schema['scalar_types'] || []
+      @parsed_schema[:scalar_types] || []
     end
 
     private