graphql-docs 5.0.0 → 5.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cbf28a678c378ebc2d54f6e5b7b24a05bd3eb577f144b9042fe11c4e7f34bd13
-  data.tar.gz: 993ad8805892c0544128baabec9dfd4f5bfb1cf16fccbe5cc43c3373036fcbbd
+  metadata.gz: cd0680cb4e1d09c704fe10170e4f48340b845a96ec6a91420a1b379cf7b217fd
+  data.tar.gz: dde6edd6ff1dc7c70eab9495cb7f27aacfa3e770815f8bd26c7ddbb71cc05793
 SHA512:
-  metadata.gz: 94e80febfa9d2c367182afd21b6a0d3e1206ec3d076a6b774ecfb96308648e4e582e818d1ac4f0b0734aaad514e46edac8a50f9ecb6baddf1370790e5eee7f38
-  data.tar.gz: 549077a6761dd67e983ab2c6bb402d5d67cfecafde214ddc57a7580439012eeb6a68ae6f0ff2091076d56eb64449aae9c055d87dc6e8a9da3fec081f51806d76
+  metadata.gz: 71424bfe5ab2367fa0c1ac4721104dab9eda558b593293dbc46d6097bd01bfc1670a45adb4a75456f980ebb7f22eaf5b30485b3c2a2fb7b6cc7ee24e91d2bad6
+  data.tar.gz: a1ac5a15d011d9f750c15745a92e3d88a1035a729fd4a9486b159a7fa263e7a0226e3340fe262fa8624428a63d452c884ba60d262b7c51e33109b83cc3700d61

data/.github/workflows/tests.yml

@@ -8,7 +8,7 @@ jobs:
 
     strategy:
       matrix:
-        ruby-version: [3.3, 3.2, 3.1]
+        ruby-version: [3.4, 3.3, 3.2, 3.1]
 
     steps:
       - uses: actions/checkout@v2

data/.rubocop.yml

@@ -6,3 +6,6 @@ Style/StringLiterals:
 
 Naming/FileName:
   Enabled: false
+
+Layout/IndentationWidth:
+  Width: 2

data/CHANGELOG.md

@@ -4,6 +4,17 @@ A concise overview of the public-facing changes to the gem from version to versi
 
 ## Unreleased
 
+## v5.2.0 - 2025-02-09
+
+- Add search filter to sidebar. Thanks @denisahearn!
+
+## v5.1.0 - 2024-12-09
+
+- List queries in the sidebar, similar to mutations. See https://github.com/brettchalupa/graphql-docs/pull/156. Thanks @denisahearn!
+- Fix Sass `@import` deprecation
+- Add ostruct and logger gems to dependencies since they're being removed from the Ruby standard library in a future release
+- Test and fixture improvements
+
 ## v5.0.0 - 2024-07-03
 
 - **breaking**: The graphql gem 2.2.0+ breaks some of the parsing and displaying of comments from a GraphQL schema file

data/CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Contribuing Guide
+# Contributing Guide
 
 Contributions to this project are welcome. If you have an idea for a bigger change, [open an issue first](https://github.com/brettchalupa/graphql-docs/issues/new/choose) and we can discuss it.
 

data/README.md

@@ -222,6 +222,15 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 `bin/rake test` to run the tests. You can also run `bin/console` for
 an interactive prompt that will allow you to experiment.
 
+### Releasing a new version of the gem
+
+1. Update CHANGELOG.md
+2. Bump the version in `lib/graphql-docs/version.rb`
+3. Make a commit and tag it with `git commit -a vX.X.X`
+4. Push the commit and tags to GitHub: `git push origin main && git push --tags`
+5. Build the gem: `gem build`
+6. Push the gem to RubyGems.org: `gem push graphql-docs-X.X.X.gem`
+
 ## Sample Site
 
 Clone this repository and run:

data/graphql-docs.gemspec

@@ -44,9 +44,11 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'gemoji', '~> 3.0'
   spec.add_dependency 'html-pipeline', '>= 2.14.3', '~> 2.14'
   spec.add_dependency 'sass-embedded', '~> 1.58'
+  spec.add_dependency 'ostruct', '~> 0.6'
+  spec.add_dependency 'logger', '~> 1.6'
 
   spec.add_development_dependency 'html-proofer', '~> 3.4'
-  spec.add_development_dependency 'minitest', '~> 5.0'
+  spec.add_development_dependency 'minitest', '~> 5.24'
   spec.add_development_dependency 'minitest-focus', '~> 1.1'
   spec.add_development_dependency 'rake', '~> 13.0'
   spec.add_development_dependency 'rubocop', '~> 1.37'

data/lib/graphql-docs/configuration.rb

@@ -32,6 +32,7 @@ module GraphQLDocs
 
         operations: "#{File.dirname(__FILE__)}/layouts/graphql_operations.html",
         objects: "#{File.dirname(__FILE__)}/layouts/graphql_objects.html",
+        queries: "#{File.dirname(__FILE__)}/layouts/graphql_queries.html",
         mutations: "#{File.dirname(__FILE__)}/layouts/graphql_mutations.html",
         interfaces: "#{File.dirname(__FILE__)}/layouts/graphql_interfaces.html",
         enums: "#{File.dirname(__FILE__)}/layouts/graphql_enums.html",

data/lib/graphql-docs/generator.rb

@@ -17,7 +17,7 @@ module GraphQLDocs
 
       @renderer = @options[:renderer].new(@parsed_schema, @options)
 
-      %i[operations objects mutations interfaces enums unions input_objects scalars directives].each do |sym|
+      %i[operations objects queries mutations interfaces enums unions input_objects scalars directives].each do |sym|
         raise IOError, "`#{sym}` template #{@options[:templates][sym]} was not found" unless File.exist?(@options[:templates][sym])
 
         instance_variable_set("@graphql_#{sym}_template", ERB.new(File.read(@options[:templates][sym])))
@@ -52,8 +52,9 @@ module GraphQLDocs
     def generate
       FileUtils.rm_rf(@options[:output_dir]) if @options[:delete_output]
 
-      has_query = create_graphql_query_pages
+      has_query = create_graphql_operation_pages
       create_graphql_object_pages
+      create_graphql_query_pages
       create_graphql_mutation_pages
       create_graphql_interface_pages
       create_graphql_enum_pages
@@ -96,7 +97,7 @@ module GraphQLDocs
       true
     end
 
-    def create_graphql_query_pages
+    def create_graphql_operation_pages
       graphql_operation_types.each do |query_type|
         metadata = ''
         next unless query_type[:name] == graphql_root_types['query']
@@ -129,6 +130,15 @@ module GraphQLDocs
       end
     end
 
+    def create_graphql_query_pages
+      graphql_query_types.each do |query|
+        opts = default_generator_options(type: query)
+
+        contents = @graphql_queries_template.result(OpenStruct.new(opts).instance_eval { binding })
+        write_file('query', query[:name], contents)
+      end
+    end
+
     def create_graphql_mutation_pages
       graphql_mutation_types.each do |mutation|
         opts = default_generator_options(type: mutation)

data/lib/graphql-docs/helpers.rb

@@ -36,6 +36,10 @@ module GraphQLDocs
       @parsed_schema[:operation_types] || []
     end
 
+    def graphql_query_types
+      @parsed_schema[:query_types] || []
+    end
+
     def graphql_mutation_types
       @parsed_schema[:mutation_types] || []
     end

data/lib/graphql-docs/landing_pages/query.md

@@ -1,4 +1,8 @@
 ---
 title: Queries
 ---
-Every GraphQL schema has a root type for both queries and mutations. The [query type](http://spec.graphql.org/draft/#sec-Type-System) defines GraphQL operations that retrieve data from the server.
+Every GraphQL schema has a root type for both queries and mutations.
+
+The query type defines GraphQL operations that retrieve data from the server.
+
+For more information, see [the GraphQL spec](http://spec.graphql.org/draft/#sec-Type-System).

data/lib/graphql-docs/layouts/assets/_sass/_sidebar.scss

@@ -69,6 +69,38 @@
       }
     }
   }
+  #search {
+    display: flex;
+    position: relative;
+    align-items: center;
+    border: 1px solid #ddd;
+    border-radius: 5px;
+    padding: 0.01em 16px;
+    margin-bottom: 20px;
+
+    img {
+      position: absolute;
+      left: 10px;
+      height: 16px;
+      width: 16px;
+    }
+
+    input {
+      height: 24px;
+      line-height: 1.5;
+      width: 100%;
+      padding-left: 15px;
+      background-color: transparent;
+      color: #444;
+      border: none;
+      font-size: 14px;
+      font-family: 'ProximaNova-Semibold';
+    }
+
+    input:focus {
+      outline: none;
+    }
+  }
 }
 
 #sidebar-mobile {

data/lib/graphql-docs/layouts/assets/css/screen.scss

@@ -1,7 +1,8 @@
 @charset "utf-8";
 
-@import "../_sass/_normalize.scss";
-@import "../_sass/_fonts";
+@use "sass:meta";
+@use "../_sass/_normalize.scss";
+@use "../_sass/_fonts";
 
 body {
   font-family: 'Source Sans Pro', 'Helvetica Neue', Helvetica, Arial, sans-serif;
@@ -39,11 +40,11 @@ em {
   font-family: 'ProximaNova-Semibold';
 }
 
-@import '../_sass/_header';
-@import '../_sass/_sidebar';
-@import '../_sass/_content';
-@import '../_sass/_types';
-@import '../_sass/_mobile';
-@import '../_sass/_api-box';
-@import '../_sass/_syntax';
-@import '../_sass/_deprecations';
+@include meta.load-css('../_sass/_header');
+@include meta.load-css('../_sass/_sidebar');
+@include meta.load-css('../_sass/_content');
+@include meta.load-css('../_sass/_types');
+@include meta.load-css('../_sass/_mobile');
+@include meta.load-css('../_sass/_api-box');
+@include meta.load-css('../_sass/_syntax');
+@include meta.load-css('../_sass/_deprecations');

data/lib/graphql-docs/layouts/assets/images/search.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
+  <path d="M15.5 14h-.79l-.28-.27C15.41 12.59 16 11.11 16 9.5 16 5.91 13.09 3 9.5 3S3 5.91 3 9.5 5.91 16 9.5 16c1.61 0 3.09-.59 4.23-1.57l.27.28v.79l5 4.99L20.49 19zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14" />
+</svg>

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

@@ -9,16 +9,71 @@
     <script src="https://cdnjs.cloudflare.com/ajax/libs/anchor-js/3.2.2/anchor.min.js"></script>
     <script>
 
-    // Add anchors on DOMContentLoaded
     document.addEventListener("DOMContentLoaded", function(event) {
+      // Add anchors
       anchors.options = {
         placement: 'left',
         visible: 'hover',
         icon: '¶'
       };
       anchors.add('h2, h3, h4, h5, h6, .anchored');
+
+      // Add listener for search filter input
+      const sidebarDiv = document.getElementById('sidebar');
+      const searchDiv = sidebarDiv.querySelector('#search')
+
+      if (searchDiv) {
+        const searchInput = searchDiv.querySelector('input');
+        const menuElements = sidebarDiv.querySelectorAll('ul.menu-root');
+
+        const listener = debounce((event) => {
+          const searchValue = event.target.value;
+          applySearchFilter(searchValue, menuElements)
+        }, 500);
+
+        searchInput.addEventListener('input', listener);
+      }
     });
 
+    function debounce(func, wait) {
+      let timeout;
+
+      return function executedFunction(...args) {
+        const later = () => {
+          clearTimeout(timeout);
+          func(...args);
+        };
+
+        clearTimeout(timeout);
+        timeout = setTimeout(later, wait);
+      };
+    }
+
+    function applySearchFilter(searchValue, menuElements) {
+      menuElements.forEach(menuElement => {
+        const listElements = menuElement.getElementsByTagName('li');
+        let hasVisibleElements = false;
+        Array.from(listElements).forEach(listElement => {
+          let contains = true
+          if (searchValue.length > 0) {
+            const anchorElement = listElement.querySelector('a');
+            const textContent = anchorElement.innerText;
+            contains = textContent.toLowerCase().includes(searchValue.toLowerCase());
+          }
+
+          // Hide the list element if its text does not contain the search value
+          listElement.style.display = contains ? '' : 'none';
+
+          if (contains) {
+            hasVisibleElements = true;
+          }
+        });
+
+        // Hide the entire menu if none of the list items are visible
+        const menuParentElement = menuElement.closest('li')
+        menuParentElement.style.display = hasVisibleElements ? '' : 'none';
+      });
+    }
     </script>
   </head>
   <body>

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

@@ -1,19 +1,3 @@
 <h1><%= type[:name] %></h1>
 
 <%= type[:description] %>
-
-<% unless type[:connections].empty? %>
-
-<h2>Connections</h2>
-
-<%= include.('connections.html', connections: type[:connections]) %>
-
-<% end %>
-
-<% unless type[:fields].empty? %>
-
-<h2>Fields</h2>
-
-<%= include.('fields.html', fields: type[:fields]) %>
-
-<% end %>

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

@@ -0,0 +1,22 @@
+<h1><%= type[:name] %></h1>
+
+<%= include.('notices.html', notices: type[:notices]) %>
+
+<%= type[:description] %>
+
+<% if !type[:arguments].empty? %>
+
+<h2>Arguments</h2>
+
+<%= include.('fields.html', fields: type[:arguments]) %>
+
+<% end %>
+
+
+<% if !type[:return_fields].empty? %>
+
+<h2>Return fields</h2>
+
+<%= include.('fields.html', fields: type[:return_fields]) %>
+
+<% end %>

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

@@ -1,3 +1,7 @@
+<div id="search">
+  <img src="<%= base_url %>/assets/images/search.svg">
+  <input autocomplete="off" placeholder="Search" />
+</div>
 <ul class="categories">
   <li>
     <ul class="menu-root">
@@ -7,7 +11,7 @@
   </li>
 
   <li>
-    <p>Queries</p>
+    <p>Operations</p>
     <ul class="menu-root">
       <li>
         <a href="<%= base_url %>/operation/query/" class="sidebar-link<% if title == "Query" %> current<% end %>">
@@ -23,12 +27,12 @@
   </li>
 
   <li>
-    <p><a href="<%= base_url %>/object">Objects</a></p>
+    <p><a href="<%= base_url %>/operation/query">Queries</a></p>
     <ul class="menu-root">
-      <% graphql_object_types.().each do |type| %>
-        <% @name = type[:name] %>
+      <% graphql_query_types.().each do |type| %>
+      <% @name = type[:name] %>
       <li>
-        <a href="<%= base_url %>/object/<%= @name.downcase %>/" class="sidebar-link<% if title == @name %> current<% end %>">
+        <a href="<%= base_url %>/query/<%= @name.downcase %>/" class="sidebar-link<% if title == @name %> current<% end %>">
           <%= @name %>
         </a>
       </li>
@@ -50,6 +54,20 @@
     </ul>
   </li>
 
+  <li>
+    <p><a href="<%= base_url %>/object">Objects</a></p>
+    <ul class="menu-root">
+      <% graphql_object_types.().each do |type| %>
+        <% @name = type[:name] %>
+      <li>
+        <a href="<%= base_url %>/object/<%= @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">

data/lib/graphql-docs/parser.rb

@@ -21,6 +21,7 @@ module GraphQLDocs
 
       @processed_schema = {
         operation_types: [],
+        query_types: [],
         mutation_types: [],
         object_types: [],
         interface_types: [],
@@ -51,8 +52,25 @@ module GraphQLDocs
           if data[:name] == root_types['query']
             data[:interfaces] = object.interfaces.map(&:graphql_name).sort
             data[:fields], data[:connections] = fetch_fields(object.fields, object.graphql_name)
-
             @processed_schema[:operation_types] << data
+
+            object.fields.each_value do |query|
+              h = {}
+
+              h[:notices] = @options[:notices].call([object.graphql_name, query.graphql_name].join('.'))
+              h[:name] = query.graphql_name
+              h[:description] = query.description
+              h[:arguments], = fetch_fields(query.arguments, [object.graphql_name, query.graphql_name].join('.'))
+
+              return_type = query.type
+              if return_type.unwrap.respond_to?(:fields)
+                h[:return_fields], = fetch_fields(return_type.unwrap.fields, return_type.graphql_name)
+              else # it is a scalar return type
+                h[:return_fields], = fetch_fields({ return_type.graphql_name => query }, return_type.graphql_name)
+              end
+
+              @processed_schema[:query_types] << h
+            end
           elsif data[:name] == root_types['mutation']
             @processed_schema[:operation_types] << data
 

data/lib/graphql-docs/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GraphQLDocs
-  VERSION = '5.0.0'
+  VERSION = '5.2.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: graphql-docs
 version: !ruby/object:Gem::Version
-  version: 5.0.0
+  version: 5.2.0
 platform: ruby
 authors:
 - Brett Chalupa
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-07-03 00:00:00.000000000 Z
+date: 2025-02-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphql
@@ -121,6 +121,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.58'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
 - !ruby/object:Gem::Dependency
   name: html-proofer
   requirement: !ruby/object:Gem::Requirement
@@ -141,14 +169,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '5.24'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '5.24'
 - !ruby/object:Gem::Dependency
   name: minitest-focus
   requirement: !ruby/object:Gem::Requirement
@@ -294,6 +322,7 @@ files:
 - lib/graphql-docs/layouts/assets/images/graphiql.png
 - lib/graphql-docs/layouts/assets/images/menu.png
 - lib/graphql-docs/layouts/assets/images/navbar.png
+- lib/graphql-docs/layouts/assets/images/search.svg
 - lib/graphql-docs/layouts/assets/webfonts/2C4B9D_B_0.eot
 - lib/graphql-docs/layouts/assets/webfonts/2C4B9D_B_0.ttf
 - lib/graphql-docs/layouts/assets/webfonts/2C4B9D_B_0.woff
@@ -318,6 +347,7 @@ files:
 - lib/graphql-docs/layouts/graphql_mutations.html
 - lib/graphql-docs/layouts/graphql_objects.html
 - lib/graphql-docs/layouts/graphql_operations.html
+- lib/graphql-docs/layouts/graphql_queries.html
 - lib/graphql-docs/layouts/graphql_scalars.html
 - lib/graphql-docs/layouts/graphql_unions.html
 - lib/graphql-docs/layouts/includes/arguments.html
@@ -355,7 +385,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.7
+rubygems_version: 3.3.27
 signing_key:
 specification_version: 4
 summary: Easily generate beautiful documentation from your GraphQL schema.