graphql-docs 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 95ab4bc20c02f63be2acd6f1383fd57184719a7e
-  data.tar.gz: 79679c4f467ceef22e31677a22b4706011c555c6
+  metadata.gz: 540afb95d491f00898705c8bd73fdb8a31d685c9
+  data.tar.gz: 23b419944ad81f60fff9264e3691d604ffeda467
 SHA512:
-  metadata.gz: d4d9f76f49551625f2509138f44e90bae1e5643ea736b1b949a2efbd66366acb262b8710813a1afe401515c8525b788ca95a77f60163a9ee1c3c0130c148b418
-  data.tar.gz: 087bfd499ba9196fbd85c6026dd16911b0f270cc81fd162782ad0d1a70822112d55bf745906f03ab21c5d7ea196ddd80fa99c76ee01a776b28819ae0725dc4ec
+  metadata.gz: 6ee639a760366f5f240dc117d5770045700e1676eaf9abb06041009513e0a31470a3c6bd77eaf1da4642e542fdc35e2669f9ee22dff23da6ee8c2aa6ee74edf5
+  data.tar.gz: 78561641aae9442b65c565b1f198f0dc9da933bfbefc8ad1f6ad50b3d553d4670fcebf3c3d094fb5ecc18779cd2fa7b043a572fe7b1c1d4181302a8fc6e2bddb

data/.gitignore

@@ -9,3 +9,5 @@
 /tmp/
 /output/
 /test/graphql-docs/fixtures/output/
+/.sass-cache/
+/sample/

data/README.md

@@ -26,12 +26,6 @@ Simple! Call `GraphQLDocs.generate`, taking care to pass in the GraphQL endpoint
 GraphQLDocs.build(url: "http://graphql.org/swapi-graphql/")
 ```
 
-If you already have the JSON locally, great! Call the same method with `path` instead:
-
-``` ruby
-GraphQLDocs.build(path: "location/to/sw-api.json")
-```
-
 If your GraphQL endpoint requires authentication, you can provide a username or password, or an access token:
 
 ``` ruby
@@ -50,37 +44,103 @@ options = {
 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')
+```
+
 ## Breakdown
 
-There are three phases going on in one little `GraphQLDocs.build` call:
+There are several phaseses going on in one little `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.
+* `GraphQL::Parser` 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:
+If you wanted to, you could break these calls up individually. For example:
 
 ``` ruby
-client = GraphQLDocs::Client.new(options)
-response = client.fetch
+options = {}
+options[:path] = "#{File.dirname(__FILE__)}/../data/graphql/docs.json"
+my_renderer = MySuperCoolRenderer(options)
+options[:renderer] = my_renderer
 
-# do something
+options = GraphQLDocs::Configuration::GRAPHQLDOCS_DEFAULTS.merge(options)
+
+response = File.read(options[:path])
 
 parser = GraphQLDocs::Parser.new(response, options)
 parsed_schema = parser.parse
 
-# do something else
-generator = Generator.new(parsed_schema, options)
+generator = GraphQLDocs::Generator.new(parsed_schema, options)
 
 generator.generate
 ```
 
 ## Generating output
 
-The HTML generation process uses [html-pipeline](https://github.com/jch/html-pipeline) and ERB to style the output. 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.
+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:
+
+``` ruby
+class CustomRenderer
+  def initialize(options, parsed_schema)
+    @options = options
+    @parsed_schema = parsed_schema
+  end
+
+  def render(type, name, contents)
+    contents.sub(/Repository/i, 'Meow Woof!')
+  end
+end
+
+options[:path] = 'location/to/sw-api.json'
+options[:renderer] = CustomRenderer
 
-### Herlper methods
+GraphQLDocs.build(options)
+```
+
+### 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.
+
+To call these methods, you must use the dot notation, such as `<%= slugify.(text) %>`.
+
+## Configuration
+
+The following options are available:
+
+
+| Option | Description | Default |
+| :----- | :---------- | :------ |
+| `access_token` | Uses this token while making requests through `GraphQLDocs::Client`. | `nil` |
+| `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` |
+| `output_dir` | The location of the output HTML. | `./output/` |
+| `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`. | The default gem ones are found in _layouts/_.
 
 ## Development
 
 After checking out the repo, run `script/bootstrap` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+## Sample site
+
+Clone this repository and run:
+
+```
+bundle exec rake sample
+```
+
+to see some sample output.

data/Rakefile

@@ -21,3 +21,31 @@ task :console do
   ARGV.clear
   Pry.start
 end
+
+task :sample do
+  require 'graphql-docs'
+  require 'sass'
+
+  options = {}
+  options[:output_dir] = 'sample'
+  options[:delete_output] = true
+  options[:path] = File.join(File.dirname(__FILE__), 'test', 'graphql-docs', 'fixtures', 'gh-api.json')
+
+  GraphQLDocs.build(options)
+
+  assets_dir = File.join('sample', 'assets')
+  FileUtils.mkdir_p(assets_dir)
+
+  sass = File.join('sample_assets', 'css', 'screen.scss')
+  system `sass --sourcemap=none #{sass}:style.css`
+
+  FileUtils.mv('style.css', File.join('sample', 'assets/style.css'))
+
+  starting_dir = 'sample'
+  starting_file = File.join(starting_dir, 'object', 'repository', 'index.html')
+
+  puts 'Navigate to http://localhost:3000 to see the sample docs'
+  puts "Launching #{starting_file}"
+  system "open #{starting_file}"
+  system "ruby -run -e httpd #{starting_dir} -p 3000"
+end

data/graphql-docs.gemspec

@@ -20,15 +20,14 @@ 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.11'
+  spec.add_dependency 'faraday', '< 0.10'#'~> 0.9'
   spec.add_dependency 'graphql', '~> 1.4'
 
   # rendering
-  spec.add_dependency 'html-pipeline', '2.5.0'
+  spec.add_dependency 'html-pipeline', '~> 2.2'
   spec.add_dependency 'github-markdown', '0.6.9'
   spec.add_dependency 'extended-markdown-filter', '~> 0.4'
   spec.add_dependency 'gemoji', '2.1.0'
-  spec.add_dependency 'page-toc-filter', '~> 0.0.1'
 
   spec.add_development_dependency 'awesome_print'
   spec.add_development_dependency 'bundler', '~> 1.14'
@@ -37,5 +36,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'pry', '~> 0.10.0'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rubocop-github'
+  spec.add_development_dependency 'sass', '~> 3.4'
   spec.add_development_dependency 'webmock', '~> 2.3'
 end

data/lib/graphql-docs.rb

@@ -1,8 +1,9 @@
 require 'graphql-docs/client'
+require 'graphql-docs/helpers'
+require 'graphql-docs/renderer'
 require 'graphql-docs/configuration'
 require 'graphql-docs/generator'
 require 'graphql-docs/parser'
-require 'graphql-docs/renderer'
 require 'graphql-docs/version'
 
 begin
@@ -32,7 +33,7 @@ module GraphQLDocs
       parser = GraphQLDocs::Parser.new(response, options)
       parsed_schema = parser.parse
 
-      generator = Generator.new(parsed_schema, options)
+      generator = GraphQLDocs::Generator.new(parsed_schema, options)
 
       generator.generate
     end

data/lib/graphql-docs/configuration.rb

@@ -9,18 +9,22 @@ module GraphQLDocs
       url: nil,
 
       # Generating
+      delete_output: false,
       output_dir: './output/',
       pipeline_config: {
         pipeline:
           %i(ExtendedMarkdownFilter
            EmojiFilter
-           PageTocFilter),
+           TableOfContentsFilter),
         context: {
           gfm: false,
           asset_root: 'https://a248.e.akamai.net/assets.github.com/images/icons'
         }
       },
+      renderer: GraphQLDocs::Renderer,
+
       templates: {
+        default: "#{File.dirname(__FILE__)}/layouts/default.html",
         includes: "#{File.dirname(__FILE__)}/layouts/includes",
         objects: "#{File.dirname(__FILE__)}/layouts/graphql_objects.html",
         mutations: "#{File.dirname(__FILE__)}/layouts/graphql_mutations.html",
@@ -30,6 +34,6 @@ module GraphQLDocs
         input_objects: "#{File.dirname(__FILE__)}/layouts/graphql_input_objects.html",
         scalars: "#{File.dirname(__FILE__)}/layouts/graphql_scalars.html"
       }
-    }
+    }.freeze
   end
 end

data/lib/graphql-docs/generator.rb

@@ -1,15 +1,16 @@
 require 'erb'
-require 'graphql-docs/generator/helpers'
 
 module GraphQLDocs
   class Generator
     include Helpers
 
+    attr_accessor :parsed_schema
+
     def initialize(parsed_schema, options)
       @parsed_schema = parsed_schema
       @options = options
 
-      @renderer = Renderer.new(@options)
+      @renderer = @options[:renderer].new(@options, @parsed_schema)
 
       @graphql_object_template = ERB.new(File.read(@options[:templates][:objects]))
       @graphql_mutations_template = ERB.new(File.read(@options[:templates][:mutations]))
@@ -21,7 +22,7 @@ module GraphQLDocs
     end
 
     def generate
-      FileUtils.rm_rf(@options[:output_dir])
+      FileUtils.rm_rf(@options[:output_dir]) if @options[:delete_output]
 
       create_graphql_object_pages
       create_graphql_mutation_pages
@@ -45,8 +46,10 @@ module GraphQLDocs
 
     def create_graphql_mutation_pages
       graphql_mutation_types.each do |mutation|
-        input = graphql_input_object_types.find { |t| t['name'] = mutation['args'].first['type']['ofType']['name'] }
-        payload = graphql_object_types.find { |t| t['name'] == mutation['type']['name'] }
+        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 = { type: mutation, input_fields: input, return_fields: payload }.merge(helper_methods)
 
@@ -102,39 +105,11 @@ module GraphQLDocs
 
     private
 
-    def graphql_mutation_types
-      graphql_object_types.find { |t| t['name'] == 'Mutation' }['fields']
-    end
-
-    def graphql_object_types
-      @parsed_schema['object_types']
-    end
-
-    def graphql_interface_types
-      @parsed_schema['interface_types']
-    end
-
-    def graphql_enum_types
-      @parsed_schema['enum_types']
-    end
-
-    def graphql_union_types
-      @parsed_schema['union_types']
-    end
-
-    def graphql_input_object_types
-      @parsed_schema['input_object_types']
-    end
-
-    def graphql_scalar_types
-      @parsed_schema['scalar_types']
-    end
-
     def write_file(type, name, contents)
       path = File.join(@options[:output_dir], type, name.downcase)
       FileUtils.mkdir_p(path)
-      contents = @renderer.render(contents)
-      File.write(File.join(path, 'index.html'), contents)
+      contents = @renderer.render(type, name, contents)
+      File.write(File.join(path, 'index.html'), contents) unless contents.nil?
     end
   end
 end

data/lib/graphql-docs/helpers.rb

@@ -0,0 +1,74 @@
+module GraphQLDocs
+  module Helpers
+    SLUGIFY_PRETTY_REGEXP = Regexp.new("[^[:alnum:]._~!$&'()+,;=@]+").freeze
+
+    attr_accessor :templates
+
+    def slugify(str)
+      slug = str.gsub(SLUGIFY_PRETTY_REGEXP, '-')
+      slug.gsub!(%r!^\-|\-$!i, '')
+      slug.downcase
+    end
+
+    def include(filename, opts = {})
+      template = fetch_include(filename)
+      template.result(OpenStruct.new(opts.merge(helper_methods)).instance_eval { binding })
+    end
+
+    def markdown(string)
+      GitHub::Markdown.render(string || 'n/a')
+    end
+
+    def graphql_mutation_types
+      @parsed_schema['mutation_types']
+    end
+
+    def graphql_object_types
+      @parsed_schema['object_types']
+    end
+
+    def graphql_interface_types
+      @parsed_schema['interface_types']
+    end
+
+    def graphql_enum_types
+      @parsed_schema['enum_types']
+    end
+
+    def graphql_union_types
+      @parsed_schema['union_types']
+    end
+
+    def graphql_input_object_types
+      @parsed_schema['input_object_types']
+    end
+
+    def graphql_scalar_types
+      @parsed_schema['scalar_types']
+    end
+
+    private
+
+    def fetch_include(filename)
+      @templates ||= {}
+
+      return @templates[filename] unless @templates[filename].nil?
+
+      @templates[filename] = ERB.new(File.read(File.join(@options[:templates][:includes], filename)))
+      @templates[filename]
+    end
+
+    def helper_methods
+      return @helper_methods if defined?(@helper_methods)
+
+      @helper_methods = {}
+
+      Helpers.instance_methods.each do |name|
+        next if name == :helper_methods
+        @helper_methods[name] = method(name)
+      end
+
+      @helper_methods
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <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>
+    <link href='https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,300,200,300italic,400italic' rel='stylesheet' type='text/css'>
+    <link rel="stylesheet" href="../../assets/style.css">
+    <script src="https://code.jquery.com/jquery-3.0.0.min.js" integrity="sha256-JmvOoLtYsmqlsWxa7mDSLMwa6dZ9rrIdtrrVYRnDRH0=" crossorigin="anonymous"></script>
+  </head>
+  <body>
+
+    <div id="wrap">
+      <div id="header">
+      </div>
+      <div id="sidebar">
+        <%= include.('sidebar.html') %>
+      </div>
+      <div id="content">
+
+        <h1><%= name %></h1>
+
+        <%= contents %>
+
+      </div>
+
+      <!-- mobile only -->
+      <div id="mobile-header">
+        <a class="menu-button"></a>
+        <a class="logo" href="/">
+
+        </a>
+      </div>
+      <div id="mobile-shade"></div>
+
+    </div>
+  </body>
+</html>