graphql-docs 4.0.0 → 5.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/.github/workflows/tests.yml +10 -10
- data/.rubocop.yml +3 -0
- data/CHANGELOG.md +17 -1
- data/README.md +41 -40
- data/exe/graphql-docs +6 -0
- data/graphql-docs.gemspec +5 -3
- data/lib/graphql-docs/configuration.rb +1 -0
- data/lib/graphql-docs/generator.rb +17 -5
- data/lib/graphql-docs/helpers.rb +5 -0
- data/lib/graphql-docs/landing_pages/enum.md +1 -1
- data/lib/graphql-docs/landing_pages/input_object.md +1 -1
- data/lib/graphql-docs/landing_pages/interface.md +1 -1
- data/lib/graphql-docs/landing_pages/mutation.md +1 -1
- data/lib/graphql-docs/landing_pages/object.md +1 -1
- data/lib/graphql-docs/landing_pages/query.md +5 -1
- data/lib/graphql-docs/landing_pages/scalar.md +1 -1
- data/lib/graphql-docs/landing_pages/union.md +1 -1
- data/lib/graphql-docs/layouts/assets/css/screen.scss +11 -10
- data/lib/graphql-docs/layouts/graphql_operations.html +0 -16
- data/lib/graphql-docs/layouts/graphql_queries.html +22 -0
- data/lib/graphql-docs/layouts/includes/sidebar.html +19 -5
- data/lib/graphql-docs/parser.rb +23 -1
- data/lib/graphql-docs/renderer.rb +1 -0
- data/lib/graphql-docs/version.rb +1 -1
- metadata +38 -9
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 6c2c88bc1065c52ba30b33a2dc65ddc2c72c61e4e20d0d001f09492cce5f24ea
|
|
4
|
+
data.tar.gz: 76fa1d45d5953b8a9ac9cfa38a97b3c6a33f5daf6880a113a90c37a623e9bf19
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: bf384c8d7749b01cfa3f78c578e6af5e9196cbc002eb6106bcedc2fd1b26197c7ea08160be3fd84017a078e455b845a9af290abce67829712200009af1039da8
|
|
7
|
+
data.tar.gz: adb18b1a5f02041c86ca0a314765efdf59ab992cf7b766796a8560491d1878b7045d695fbc38bd7c74ed7f02957b72fc05196521d1fabe883b1e021ada29570e
|
data/.github/workflows/tests.yml
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
name: Ruby
|
|
2
2
|
|
|
3
|
-
on: [push,pull_request]
|
|
3
|
+
on: [push, pull_request]
|
|
4
4
|
|
|
5
5
|
jobs:
|
|
6
6
|
test:
|
|
@@ -8,14 +8,14 @@ jobs:
|
|
|
8
8
|
|
|
9
9
|
strategy:
|
|
10
10
|
matrix:
|
|
11
|
-
ruby-version: [3.
|
|
11
|
+
ruby-version: [3.4.0-preview2, 3.3, 3.2, 3.1]
|
|
12
12
|
|
|
13
13
|
steps:
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
14
|
+
- uses: actions/checkout@v2
|
|
15
|
+
- name: Set up Ruby ${{ matrix.ruby-version }}
|
|
16
|
+
uses: ruby/setup-ruby@v1
|
|
17
|
+
with:
|
|
18
|
+
ruby-version: ${{ matrix.ruby-version }}
|
|
19
|
+
bundler-cache: true
|
|
20
|
+
- name: Run the test suite
|
|
21
|
+
run: bundle exec rake
|
data/.rubocop.yml
CHANGED
data/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,22 @@ A concise overview of the public-facing changes to the gem from version to versi
|
|
|
4
4
|
|
|
5
5
|
## Unreleased
|
|
6
6
|
|
|
7
|
+
## v5.1.0 - 2024-12-09
|
|
8
|
+
|
|
9
|
+
- List queries in the sidebar, similar to mutations. See https://github.com/brettchalupa/graphql-docs/pull/156. Thanks @denisahearn!
|
|
10
|
+
- Fix Sass `@import` deprecation
|
|
11
|
+
- Add ostruct and logger gems to dependencies since they're being removed from the Ruby standard library in a future release
|
|
12
|
+
- Test and fixture improvements
|
|
13
|
+
|
|
14
|
+
## v5.0.0 - 2024-07-03
|
|
15
|
+
|
|
16
|
+
- **breaking**: The graphql gem 2.2.0+ breaks some of the parsing and displaying of comments from a GraphQL schema file
|
|
17
|
+
- **breaking**: Ruby 2.6, 2.7, 3.0 are no longer supported as they are End of Life (EOL)
|
|
18
|
+
- feat: CLI version flag: `graphql-docs --version` / `graphql-docs -v`
|
|
19
|
+
- fix: CLI now works outside of a Bundler project
|
|
20
|
+
- fix: test suite
|
|
21
|
+
- chore: switch to sess-embedded gem for more maintained dependency
|
|
22
|
+
|
|
7
23
|
## v4.0.0 - 2023-01-26
|
|
8
24
|
|
|
9
25
|
- **Breaking change**: drop support for Ruby 2.5 and earlier
|
|
@@ -12,7 +28,7 @@ A concise overview of the public-facing changes to the gem from version to versi
|
|
|
12
28
|
- Fixes:
|
|
13
29
|
- Upgrade commonmarker to latest ver to address security vulnerabilities
|
|
14
30
|
- commonmarker pinned to version without security vulnerability
|
|
15
|
-
- Chores
|
|
31
|
+
- Chores:
|
|
16
32
|
- Dev env refresh
|
|
17
33
|
|
|
18
34
|
## v3.0.1 - 2022-10-14
|
data/README.md
CHANGED
|
@@ -8,13 +8,13 @@ Ruby library and CLI for easily generating beautiful documentation from your Gra
|
|
|
8
8
|
|
|
9
9
|
Add the gem to your project with this command:
|
|
10
10
|
|
|
11
|
-
```
|
|
11
|
+
```console
|
|
12
12
|
bundle add graphql-docs
|
|
13
13
|
```
|
|
14
14
|
|
|
15
15
|
Or install it yourself as:
|
|
16
16
|
|
|
17
|
-
```
|
|
17
|
+
```console
|
|
18
18
|
gem install graphql-docs
|
|
19
19
|
```
|
|
20
20
|
|
|
@@ -22,7 +22,7 @@ gem install graphql-docs
|
|
|
22
22
|
|
|
23
23
|
GraphQLDocs can be used as a Ruby library to build the documentation website. Using it as a Ruby library allows for more control and using every supported option. Here's an example:
|
|
24
24
|
|
|
25
|
-
```
|
|
25
|
+
```ruby
|
|
26
26
|
# pass in a filename
|
|
27
27
|
GraphQLDocs.build(filename: filename)
|
|
28
28
|
|
|
@@ -36,9 +36,9 @@ end
|
|
|
36
36
|
GraphQLDocs.build(schema: schema)
|
|
37
37
|
```
|
|
38
38
|
|
|
39
|
-
|
|
39
|
+
GraphQLDocs also has a simplified CLI (`graphql-docs`) that gets installed with the gem:
|
|
40
40
|
|
|
41
|
-
```
|
|
41
|
+
```console
|
|
42
42
|
graphql-docs schema.graphql
|
|
43
43
|
```
|
|
44
44
|
|
|
@@ -46,7 +46,7 @@ That will generate the output in the `output` dir.
|
|
|
46
46
|
|
|
47
47
|
See all of the supported CLI options with:
|
|
48
48
|
|
|
49
|
-
```
|
|
49
|
+
```console
|
|
50
50
|
graphql-docs -h
|
|
51
51
|
```
|
|
52
52
|
|
|
@@ -54,14 +54,14 @@ graphql-docs -h
|
|
|
54
54
|
|
|
55
55
|
There are several phases going on the single `GraphQLDocs.build` call:
|
|
56
56
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
57
|
+
- The GraphQL IDL file is read (if you passed `filename`) through `GraphQL::Client` (or simply read if you passed a string through `schema`).
|
|
58
|
+
- `GraphQL::Parser` manipulates the IDL into a slightly saner format.
|
|
59
|
+
- `GraphQL::Generator` takes that saner format and begins the process of applying items to the HTML templates.
|
|
60
|
+
- `GraphQL::Renderer` technically runs as part of the generation phase. It passes the contents of each page and converts it into HTML.
|
|
61
61
|
|
|
62
62
|
If you wanted to, you could break these calls up individually. For example:
|
|
63
63
|
|
|
64
|
-
```
|
|
64
|
+
```ruby
|
|
65
65
|
options = {}
|
|
66
66
|
options[:filename] = "#{File.dirname(__FILE__)}/../data/graphql/schema.idl"
|
|
67
67
|
options[:renderer] = MySuperCoolRenderer
|
|
@@ -80,14 +80,14 @@ generator.generate
|
|
|
80
80
|
|
|
81
81
|
## Generating output
|
|
82
82
|
|
|
83
|
-
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
|
|
83
|
+
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.
|
|
84
84
|
|
|
85
85
|
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:
|
|
86
86
|
|
|
87
|
-
|
|
88
|
-
|
|
87
|
+
- `initialize` - Takes two arguments, the parsed `schema` and the configuration `options`.
|
|
88
|
+
- `render` Takes the contents of a template page. It also takes two optional kwargs, the GraphQL `type` and its `name`. For example:
|
|
89
89
|
|
|
90
|
-
```
|
|
90
|
+
```ruby
|
|
91
91
|
class CustomRenderer
|
|
92
92
|
def initialize(parsed_schema, options)
|
|
93
93
|
@parsed_schema = parsed_schema
|
|
@@ -120,10 +120,10 @@ If you want to add additional variables for your landing pages, you can add defi
|
|
|
120
120
|
|
|
121
121
|
In your ERB layouts, there are several helper methods you can use. The helper methods are:
|
|
122
122
|
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
123
|
+
- `slugify(str)` - This slugifies the given string.
|
|
124
|
+
- `include(filename, opts)` - This embeds a template from your `includes` folder, passing along the local options provided.
|
|
125
|
+
- `markdownify(string)` - This converts a string into HTML via CommonMarker.
|
|
126
|
+
- `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`, `graphql_directive_types` - Collections of the various GraphQL types.
|
|
127
127
|
|
|
128
128
|
To call these methods within templates, you must use the dot notation, such as `<%= slugify.(text) %>`.
|
|
129
129
|
|
|
@@ -131,20 +131,20 @@ To call these methods within templates, you must use the dot notation, such as `
|
|
|
131
131
|
|
|
132
132
|
The following options are available:
|
|
133
133
|
|
|
134
|
-
| Option
|
|
135
|
-
|
|
|
136
|
-
| `filename`
|
|
137
|
-
| `schema`
|
|
138
|
-
| `output_dir`
|
|
139
|
-
| `use_default_styles` | Indicates if you want to use the default styles.
|
|
140
|
-
| `base_url`
|
|
141
|
-
| `delete_output`
|
|
142
|
-
| `pipeline_config`
|
|
143
|
-
| `renderer`
|
|
144
|
-
| `templates`
|
|
145
|
-
| `landing_pages`
|
|
146
|
-
| `classes`
|
|
147
|
-
| `notices`
|
|
134
|
+
| Option | Description | Default |
|
|
135
|
+
| :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
136
|
+
| `filename` | The location of your schema's IDL file. | `nil` |
|
|
137
|
+
| `schema` | A string representing a schema IDL file. | `nil` |
|
|
138
|
+
| `output_dir` | The location of the output HTML. | `./output/` |
|
|
139
|
+
| `use_default_styles` | Indicates if you want to use the default styles. | `true` |
|
|
140
|
+
| `base_url` | Indicates the base URL to prepend for assets and links. | `""` |
|
|
141
|
+
| `delete_output` | Deletes `output_dir` before generating content. | `false` |
|
|
142
|
+
| `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. |
|
|
143
|
+
| `renderer` | The rendering class to use. | `GraphQLDocs::Renderer` |
|
|
144
|
+
| `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`, `directives`. | The defaults are found in _lib/graphql-docs/layouts/_. |
|
|
145
|
+
| `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`, `directive`. | The defaults are found in _lib/graphql-docs/landing_pages/_. |
|
|
146
|
+
| `classes` | Additional class names you can provide to certain elements. | The full list is available in _lib/graphql-docs/configuration.rb_. |
|
|
147
|
+
| `notices` | A proc used to add notices to schema members. See _Customizing Notices_ section below. | `nil` |
|
|
148
148
|
|
|
149
149
|
### Customizing Notices
|
|
150
150
|
|
|
@@ -157,11 +157,11 @@ The proc will be called for each schema member and needs to return an array of n
|
|
|
157
157
|
|
|
158
158
|
A `notice` has the following options:
|
|
159
159
|
|
|
160
|
-
| Option
|
|
161
|
-
|
|
|
162
|
-
| `body`
|
|
163
|
-
| `title`
|
|
164
|
-
| `class`
|
|
160
|
+
| Option | Description |
|
|
161
|
+
| :------------ | :-------------------------------------------------------- |
|
|
162
|
+
| `body` | CommonMark body of the notice |
|
|
163
|
+
| `title` | Optional title of the notice |
|
|
164
|
+
| `class` | Optional CSS class for the wrapper `<div>` of the notice |
|
|
165
165
|
| `title_class` | Optional CSS class for the `<span>` of the notice's title |
|
|
166
166
|
|
|
167
167
|
Example of a `notices` proc that adds a notice to the `TeamDiscussion` type:
|
|
@@ -197,8 +197,9 @@ The format of `schema_member_path` is a dot delimited path to the schema member.
|
|
|
197
197
|
|
|
198
198
|
## Supported Ruby Versions
|
|
199
199
|
|
|
200
|
-
The gem
|
|
201
|
-
|
|
200
|
+
The gem officially supports **Ruby 3.1 and newer**.
|
|
201
|
+
|
|
202
|
+
Any dropping of Ruby version support is considered a breaking change and means a major release for the gem.
|
|
202
203
|
|
|
203
204
|
## Upgrading
|
|
204
205
|
|
data/exe/graphql-docs
CHANGED
|
@@ -28,9 +28,15 @@ OptionParser.new do |parser|
|
|
|
28
28
|
parser.on("-o", "--output-dir DIR", "Where the site is generated to, defaults to ./output")
|
|
29
29
|
parser.on("-d", "--delete-output", "Delete the output-dir before generating, defaults to false")
|
|
30
30
|
parser.on("-b", "--base-url URL", "URL to preprend for assets and links, defaults to \"\"")
|
|
31
|
+
parser.on("-v", "--version", "Show the version")
|
|
31
32
|
parser.on("--verbose", "Run in verbose mode")
|
|
32
33
|
end.parse!(into: opts)
|
|
33
34
|
|
|
35
|
+
if opts[:version]
|
|
36
|
+
puts("v#{GraphQLDocs::VERSION}")
|
|
37
|
+
exit
|
|
38
|
+
end
|
|
39
|
+
|
|
34
40
|
def err(msg)
|
|
35
41
|
abort("#{NAME}: Error: #{msg}")
|
|
36
42
|
end
|
data/graphql-docs.gemspec
CHANGED
|
@@ -33,7 +33,7 @@ Gem::Specification.new do |spec|
|
|
|
33
33
|
spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
|
|
34
34
|
spec.require_paths = ['lib']
|
|
35
35
|
|
|
36
|
-
spec.required_ruby_version = '>=
|
|
36
|
+
spec.required_ruby_version = '>= 3.1'
|
|
37
37
|
|
|
38
38
|
spec.add_dependency 'graphql', '~> 2.0'
|
|
39
39
|
|
|
@@ -43,10 +43,12 @@ Gem::Specification.new do |spec|
|
|
|
43
43
|
spec.add_dependency 'extended-markdown-filter', '~> 0.4'
|
|
44
44
|
spec.add_dependency 'gemoji', '~> 3.0'
|
|
45
45
|
spec.add_dependency 'html-pipeline', '>= 2.14.3', '~> 2.14'
|
|
46
|
-
spec.add_dependency '
|
|
46
|
+
spec.add_dependency 'sass-embedded', '~> 1.58'
|
|
47
|
+
spec.add_dependency 'ostruct', '~> 0.6'
|
|
48
|
+
spec.add_dependency 'logger', '~> 1.6'
|
|
47
49
|
|
|
48
50
|
spec.add_development_dependency 'html-proofer', '~> 3.4'
|
|
49
|
-
spec.add_development_dependency 'minitest', '~> 5.
|
|
51
|
+
spec.add_development_dependency 'minitest', '~> 5.24'
|
|
50
52
|
spec.add_development_dependency 'minitest-focus', '~> 1.1'
|
|
51
53
|
spec.add_development_dependency 'rake', '~> 13.0'
|
|
52
54
|
spec.add_development_dependency 'rubocop', '~> 1.37'
|
|
@@ -32,6 +32,7 @@ module GraphQLDocs
|
|
|
32
32
|
|
|
33
33
|
operations: "#{File.dirname(__FILE__)}/layouts/graphql_operations.html",
|
|
34
34
|
objects: "#{File.dirname(__FILE__)}/layouts/graphql_objects.html",
|
|
35
|
+
queries: "#{File.dirname(__FILE__)}/layouts/graphql_queries.html",
|
|
35
36
|
mutations: "#{File.dirname(__FILE__)}/layouts/graphql_mutations.html",
|
|
36
37
|
interfaces: "#{File.dirname(__FILE__)}/layouts/graphql_interfaces.html",
|
|
37
38
|
enums: "#{File.dirname(__FILE__)}/layouts/graphql_enums.html",
|
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
require 'erb'
|
|
4
4
|
require 'fileutils'
|
|
5
|
+
require 'sass-embedded'
|
|
6
|
+
require 'ostruct'
|
|
5
7
|
|
|
6
8
|
module GraphQLDocs
|
|
7
9
|
class Generator
|
|
@@ -15,7 +17,7 @@ module GraphQLDocs
|
|
|
15
17
|
|
|
16
18
|
@renderer = @options[:renderer].new(@parsed_schema, @options)
|
|
17
19
|
|
|
18
|
-
%i[operations objects mutations interfaces enums unions input_objects scalars directives].each do |sym|
|
|
20
|
+
%i[operations objects queries mutations interfaces enums unions input_objects scalars directives].each do |sym|
|
|
19
21
|
raise IOError, "`#{sym}` template #{@options[:templates][sym]} was not found" unless File.exist?(@options[:templates][sym])
|
|
20
22
|
|
|
21
23
|
instance_variable_set("@graphql_#{sym}_template", ERB.new(File.read(@options[:templates][sym])))
|
|
@@ -50,8 +52,9 @@ module GraphQLDocs
|
|
|
50
52
|
def generate
|
|
51
53
|
FileUtils.rm_rf(@options[:output_dir]) if @options[:delete_output]
|
|
52
54
|
|
|
53
|
-
has_query =
|
|
55
|
+
has_query = create_graphql_operation_pages
|
|
54
56
|
create_graphql_object_pages
|
|
57
|
+
create_graphql_query_pages
|
|
55
58
|
create_graphql_mutation_pages
|
|
56
59
|
create_graphql_interface_pages
|
|
57
60
|
create_graphql_enum_pages
|
|
@@ -84,8 +87,8 @@ module GraphQLDocs
|
|
|
84
87
|
assets_dir = File.join(File.dirname(__FILE__), 'layouts', 'assets')
|
|
85
88
|
FileUtils.mkdir_p(File.join(@options[:output_dir], 'assets'))
|
|
86
89
|
|
|
87
|
-
|
|
88
|
-
|
|
90
|
+
css = Sass.compile(File.join(assets_dir, 'css', 'screen.scss')).css
|
|
91
|
+
File.write(File.join(@options[:output_dir], 'assets', 'style.css'), css)
|
|
89
92
|
|
|
90
93
|
FileUtils.cp_r(File.join(assets_dir, 'images'), File.join(@options[:output_dir], 'assets'))
|
|
91
94
|
FileUtils.cp_r(File.join(assets_dir, 'webfonts'), File.join(@options[:output_dir], 'assets'))
|
|
@@ -94,7 +97,7 @@ module GraphQLDocs
|
|
|
94
97
|
true
|
|
95
98
|
end
|
|
96
99
|
|
|
97
|
-
def
|
|
100
|
+
def create_graphql_operation_pages
|
|
98
101
|
graphql_operation_types.each do |query_type|
|
|
99
102
|
metadata = ''
|
|
100
103
|
next unless query_type[:name] == graphql_root_types['query']
|
|
@@ -127,6 +130,15 @@ module GraphQLDocs
|
|
|
127
130
|
end
|
|
128
131
|
end
|
|
129
132
|
|
|
133
|
+
def create_graphql_query_pages
|
|
134
|
+
graphql_query_types.each do |query|
|
|
135
|
+
opts = default_generator_options(type: query)
|
|
136
|
+
|
|
137
|
+
contents = @graphql_queries_template.result(OpenStruct.new(opts).instance_eval { binding })
|
|
138
|
+
write_file('query', query[:name], contents)
|
|
139
|
+
end
|
|
140
|
+
end
|
|
141
|
+
|
|
130
142
|
def create_graphql_mutation_pages
|
|
131
143
|
graphql_mutation_types.each do |mutation|
|
|
132
144
|
opts = default_generator_options(type: mutation)
|
data/lib/graphql-docs/helpers.rb
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
3
|
require 'commonmarker'
|
|
4
|
+
require 'ostruct'
|
|
4
5
|
|
|
5
6
|
module GraphQLDocs
|
|
6
7
|
module Helpers
|
|
@@ -35,6 +36,10 @@ module GraphQLDocs
|
|
|
35
36
|
@parsed_schema[:operation_types] || []
|
|
36
37
|
end
|
|
37
38
|
|
|
39
|
+
def graphql_query_types
|
|
40
|
+
@parsed_schema[:query_types] || []
|
|
41
|
+
end
|
|
42
|
+
|
|
38
43
|
def graphql_mutation_types
|
|
39
44
|
@parsed_schema[:mutation_types] || []
|
|
40
45
|
end
|
|
@@ -6,4 +6,4 @@ title: Enums
|
|
|
6
6
|
|
|
7
7
|
Enums represent a possible set of values for a field. For example, the `Issue` object has a field called `state`. The state of an issue may be `OPEN` or `CLOSED`.
|
|
8
8
|
|
|
9
|
-
For more information, see [the GraphQL spec](
|
|
9
|
+
For more information, see [the GraphQL spec](http://spec.graphql.org/draft/#sec-Enums).
|
|
@@ -6,4 +6,4 @@ title: Input Objects
|
|
|
6
6
|
|
|
7
7
|
Input objects are best described as "composable objects" in that they contain a set of input fields that define a particular object. For example, the `AuthorInput` takes a field called `emails`. Providing a value for `emails` will transform the `AuthorInput` into a list of `User` objects which contain that email address/
|
|
8
8
|
|
|
9
|
-
For more information, see [the GraphQL spec](
|
|
9
|
+
For more information, see [the GraphQL spec](http://spec.graphql.org/draft/#sec-Input-Objects).
|
|
@@ -6,4 +6,4 @@ title: Interfaces
|
|
|
6
6
|
|
|
7
7
|
GraphQL Interfaces are a sort of "parent object" from which other objects can "inherit" from. For example, `Stars` is considered an interface, because both `Repository` and `Gist` can be starred. An interface has its own list of named fields that are shared by implementing objects.
|
|
8
8
|
|
|
9
|
-
For more information, see [the GraphQL spec](
|
|
9
|
+
For more information, see [the GraphQL spec](http://spec.graphql.org/draft/#sec-Interfaces).
|
|
@@ -8,4 +8,4 @@ Every GraphQL schema has a root type for both queries and mutations.
|
|
|
8
8
|
|
|
9
9
|
The mutation type defines how GraphQL operations change data. It is analogous to performing HTTP verbs such as `POST`, `PATCH`, and `DELETE`.
|
|
10
10
|
|
|
11
|
-
For more information, see [the GraphQL spec](
|
|
11
|
+
For more information, see [the GraphQL spec](http://spec.graphql.org/draft/#sec-Type-System).
|
|
@@ -5,4 +5,4 @@ title: Objects
|
|
|
5
5
|
|
|
6
6
|
Objects in GraphQL represent the resources that you can access. Objects can contain a list of fields, which are specifically typed. For example, the `Repository` object has a field called `name`, which is a `String`.
|
|
7
7
|
|
|
8
|
-
For more information, see [the GraphQL spec](
|
|
8
|
+
For more information, see [the GraphQL spec](http://spec.graphql.org/draft/#sec-Objects).
|
|
@@ -1,4 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Queries
|
|
3
3
|
---
|
|
4
|
-
Every GraphQL schema has a root type for both queries and mutations.
|
|
4
|
+
Every GraphQL schema has a root type for both queries and mutations.
|
|
5
|
+
|
|
6
|
+
The query type defines GraphQL operations that retrieve data from the server.
|
|
7
|
+
|
|
8
|
+
For more information, see [the GraphQL spec](http://spec.graphql.org/draft/#sec-Type-System).
|
|
@@ -6,4 +6,4 @@ title: Unions
|
|
|
6
6
|
|
|
7
7
|
A union is a type of object that can represent one of many kinds of objects. For example, a field marked as a `ReactableUnion` could be a `CommitComment`, an `Issue`, an `IssueComment`, or a `PullRequestReviewComment`, because each of those objects can be reacted on.
|
|
8
8
|
|
|
9
|
-
For more information, see [the GraphQL spec](
|
|
9
|
+
For more information, see [the GraphQL spec](http://spec.graphql.org/draft/#sec-Unions).
|
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
@charset "utf-8";
|
|
2
2
|
|
|
3
|
-
@
|
|
4
|
-
@
|
|
3
|
+
@use "sass:meta";
|
|
4
|
+
@use "../_sass/_normalize.scss";
|
|
5
|
+
@use "../_sass/_fonts";
|
|
5
6
|
|
|
6
7
|
body {
|
|
7
8
|
font-family: 'Source Sans Pro', 'Helvetica Neue', Helvetica, Arial, sans-serif;
|
|
@@ -39,11 +40,11 @@ em {
|
|
|
39
40
|
font-family: 'ProximaNova-Semibold';
|
|
40
41
|
}
|
|
41
42
|
|
|
42
|
-
@
|
|
43
|
-
@
|
|
44
|
-
@
|
|
45
|
-
@
|
|
46
|
-
@
|
|
47
|
-
@
|
|
48
|
-
@
|
|
49
|
-
@
|
|
43
|
+
@include meta.load-css('../_sass/_header');
|
|
44
|
+
@include meta.load-css('../_sass/_sidebar');
|
|
45
|
+
@include meta.load-css('../_sass/_content');
|
|
46
|
+
@include meta.load-css('../_sass/_types');
|
|
47
|
+
@include meta.load-css('../_sass/_mobile');
|
|
48
|
+
@include meta.load-css('../_sass/_api-box');
|
|
49
|
+
@include meta.load-css('../_sass/_syntax');
|
|
50
|
+
@include meta.load-css('../_sass/_deprecations');
|
|
@@ -1,19 +1,3 @@
|
|
|
1
1
|
<h1><%= type[:name] %></h1>
|
|
2
2
|
|
|
3
3
|
<%= type[:description] %>
|
|
4
|
-
|
|
5
|
-
<% unless type[:connections].empty? %>
|
|
6
|
-
|
|
7
|
-
<h2>Connections</h2>
|
|
8
|
-
|
|
9
|
-
<%= include.('connections.html', connections: type[:connections]) %>
|
|
10
|
-
|
|
11
|
-
<% end %>
|
|
12
|
-
|
|
13
|
-
<% unless type[:fields].empty? %>
|
|
14
|
-
|
|
15
|
-
<h2>Fields</h2>
|
|
16
|
-
|
|
17
|
-
<%= include.('fields.html', fields: type[:fields]) %>
|
|
18
|
-
|
|
19
|
-
<% end %>
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
<h1><%= type[:name] %></h1>
|
|
2
|
+
|
|
3
|
+
<%= include.('notices.html', notices: type[:notices]) %>
|
|
4
|
+
|
|
5
|
+
<%= type[:description] %>
|
|
6
|
+
|
|
7
|
+
<% if !type[:arguments].empty? %>
|
|
8
|
+
|
|
9
|
+
<h2>Arguments</h2>
|
|
10
|
+
|
|
11
|
+
<%= include.('fields.html', fields: type[:arguments]) %>
|
|
12
|
+
|
|
13
|
+
<% end %>
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
<% if !type[:return_fields].empty? %>
|
|
17
|
+
|
|
18
|
+
<h2>Return fields</h2>
|
|
19
|
+
|
|
20
|
+
<%= include.('fields.html', fields: type[:return_fields]) %>
|
|
21
|
+
|
|
22
|
+
<% end %>
|
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
</li>
|
|
8
8
|
|
|
9
9
|
<li>
|
|
10
|
-
<p>
|
|
10
|
+
<p>Operations</p>
|
|
11
11
|
<ul class="menu-root">
|
|
12
12
|
<li>
|
|
13
13
|
<a href="<%= base_url %>/operation/query/" class="sidebar-link<% if title == "Query" %> current<% end %>">
|
|
@@ -23,12 +23,12 @@
|
|
|
23
23
|
</li>
|
|
24
24
|
|
|
25
25
|
<li>
|
|
26
|
-
<p><a href="<%= base_url %>/
|
|
26
|
+
<p><a href="<%= base_url %>/operation/query">Queries</a></p>
|
|
27
27
|
<ul class="menu-root">
|
|
28
|
-
<%
|
|
29
|
-
|
|
28
|
+
<% graphql_query_types.().each do |type| %>
|
|
29
|
+
<% @name = type[:name] %>
|
|
30
30
|
<li>
|
|
31
|
-
<a href="<%= base_url %>/
|
|
31
|
+
<a href="<%= base_url %>/query/<%= @name.downcase %>/" class="sidebar-link<% if title == @name %> current<% end %>">
|
|
32
32
|
<%= @name %>
|
|
33
33
|
</a>
|
|
34
34
|
</li>
|
|
@@ -50,6 +50,20 @@
|
|
|
50
50
|
</ul>
|
|
51
51
|
</li>
|
|
52
52
|
|
|
53
|
+
<li>
|
|
54
|
+
<p><a href="<%= base_url %>/object">Objects</a></p>
|
|
55
|
+
<ul class="menu-root">
|
|
56
|
+
<% graphql_object_types.().each do |type| %>
|
|
57
|
+
<% @name = type[:name] %>
|
|
58
|
+
<li>
|
|
59
|
+
<a href="<%= base_url %>/object/<%= @name.downcase %>/" class="sidebar-link<% if title == @name %> current<% end %>">
|
|
60
|
+
<%= @name %>
|
|
61
|
+
</a>
|
|
62
|
+
</li>
|
|
63
|
+
<% end %>
|
|
64
|
+
</ul>
|
|
65
|
+
</li>
|
|
66
|
+
|
|
53
67
|
<li>
|
|
54
68
|
<p><a href="<%= base_url %>/interface">Interfaces</a></p>
|
|
55
69
|
<ul class="menu-root">
|
data/lib/graphql-docs/parser.rb
CHANGED
|
@@ -21,6 +21,7 @@ module GraphQLDocs
|
|
|
21
21
|
|
|
22
22
|
@processed_schema = {
|
|
23
23
|
operation_types: [],
|
|
24
|
+
query_types: [],
|
|
24
25
|
mutation_types: [],
|
|
25
26
|
object_types: [],
|
|
26
27
|
interface_types: [],
|
|
@@ -51,8 +52,25 @@ module GraphQLDocs
|
|
|
51
52
|
if data[:name] == root_types['query']
|
|
52
53
|
data[:interfaces] = object.interfaces.map(&:graphql_name).sort
|
|
53
54
|
data[:fields], data[:connections] = fetch_fields(object.fields, object.graphql_name)
|
|
54
|
-
|
|
55
55
|
@processed_schema[:operation_types] << data
|
|
56
|
+
|
|
57
|
+
object.fields.each_value do |query|
|
|
58
|
+
h = {}
|
|
59
|
+
|
|
60
|
+
h[:notices] = @options[:notices].call([object.graphql_name, query.graphql_name].join('.'))
|
|
61
|
+
h[:name] = query.graphql_name
|
|
62
|
+
h[:description] = query.description
|
|
63
|
+
h[:arguments], = fetch_fields(query.arguments, [object.graphql_name, query.graphql_name].join('.'))
|
|
64
|
+
|
|
65
|
+
return_type = query.type
|
|
66
|
+
if return_type.unwrap.respond_to?(:fields)
|
|
67
|
+
h[:return_fields], = fetch_fields(return_type.unwrap.fields, return_type.graphql_name)
|
|
68
|
+
else # it is a scalar return type
|
|
69
|
+
h[:return_fields], = fetch_fields({ return_type.graphql_name => query }, return_type.graphql_name)
|
|
70
|
+
end
|
|
71
|
+
|
|
72
|
+
@processed_schema[:query_types] << h
|
|
73
|
+
end
|
|
56
74
|
elsif data[:name] == root_types['mutation']
|
|
57
75
|
@processed_schema[:operation_types] << data
|
|
58
76
|
|
|
@@ -177,6 +195,10 @@ module GraphQLDocs
|
|
|
177
195
|
h[:description] = arg.description
|
|
178
196
|
h[:type] = generate_type(arg.type)
|
|
179
197
|
h[:default_value] = arg.default_value if arg.default_value?
|
|
198
|
+
if arg.respond_to?(:deprecation_reason) && arg.deprecation_reason
|
|
199
|
+
h[:is_deprecated] = true
|
|
200
|
+
h[:deprecation_reason] = arg.deprecation_reason
|
|
201
|
+
end
|
|
180
202
|
hash[:arguments] << h
|
|
181
203
|
end
|
|
182
204
|
end
|
data/lib/graphql-docs/version.rb
CHANGED
metadata
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: graphql-docs
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version:
|
|
4
|
+
version: 5.1.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Brett Chalupa
|
|
@@ -9,7 +9,7 @@ authors:
|
|
|
9
9
|
autorequire:
|
|
10
10
|
bindir: exe
|
|
11
11
|
cert_chain: []
|
|
12
|
-
date:
|
|
12
|
+
date: 2024-12-10 00:00:00.000000000 Z
|
|
13
13
|
dependencies:
|
|
14
14
|
- !ruby/object:Gem::Dependency
|
|
15
15
|
name: graphql
|
|
@@ -108,19 +108,47 @@ dependencies:
|
|
|
108
108
|
- !ruby/object:Gem::Version
|
|
109
109
|
version: '2.14'
|
|
110
110
|
- !ruby/object:Gem::Dependency
|
|
111
|
-
name:
|
|
111
|
+
name: sass-embedded
|
|
112
112
|
requirement: !ruby/object:Gem::Requirement
|
|
113
113
|
requirements:
|
|
114
114
|
- - "~>"
|
|
115
115
|
- !ruby/object:Gem::Version
|
|
116
|
-
version: '1.
|
|
116
|
+
version: '1.58'
|
|
117
117
|
type: :runtime
|
|
118
118
|
prerelease: false
|
|
119
119
|
version_requirements: !ruby/object:Gem::Requirement
|
|
120
120
|
requirements:
|
|
121
121
|
- - "~>"
|
|
122
122
|
- !ruby/object:Gem::Version
|
|
123
|
-
version: '1.
|
|
123
|
+
version: '1.58'
|
|
124
|
+
- !ruby/object:Gem::Dependency
|
|
125
|
+
name: ostruct
|
|
126
|
+
requirement: !ruby/object:Gem::Requirement
|
|
127
|
+
requirements:
|
|
128
|
+
- - "~>"
|
|
129
|
+
- !ruby/object:Gem::Version
|
|
130
|
+
version: '0.6'
|
|
131
|
+
type: :runtime
|
|
132
|
+
prerelease: false
|
|
133
|
+
version_requirements: !ruby/object:Gem::Requirement
|
|
134
|
+
requirements:
|
|
135
|
+
- - "~>"
|
|
136
|
+
- !ruby/object:Gem::Version
|
|
137
|
+
version: '0.6'
|
|
138
|
+
- !ruby/object:Gem::Dependency
|
|
139
|
+
name: logger
|
|
140
|
+
requirement: !ruby/object:Gem::Requirement
|
|
141
|
+
requirements:
|
|
142
|
+
- - "~>"
|
|
143
|
+
- !ruby/object:Gem::Version
|
|
144
|
+
version: '1.6'
|
|
145
|
+
type: :runtime
|
|
146
|
+
prerelease: false
|
|
147
|
+
version_requirements: !ruby/object:Gem::Requirement
|
|
148
|
+
requirements:
|
|
149
|
+
- - "~>"
|
|
150
|
+
- !ruby/object:Gem::Version
|
|
151
|
+
version: '1.6'
|
|
124
152
|
- !ruby/object:Gem::Dependency
|
|
125
153
|
name: html-proofer
|
|
126
154
|
requirement: !ruby/object:Gem::Requirement
|
|
@@ -141,14 +169,14 @@ dependencies:
|
|
|
141
169
|
requirements:
|
|
142
170
|
- - "~>"
|
|
143
171
|
- !ruby/object:Gem::Version
|
|
144
|
-
version: '5.
|
|
172
|
+
version: '5.24'
|
|
145
173
|
type: :development
|
|
146
174
|
prerelease: false
|
|
147
175
|
version_requirements: !ruby/object:Gem::Requirement
|
|
148
176
|
requirements:
|
|
149
177
|
- - "~>"
|
|
150
178
|
- !ruby/object:Gem::Version
|
|
151
|
-
version: '5.
|
|
179
|
+
version: '5.24'
|
|
152
180
|
- !ruby/object:Gem::Dependency
|
|
153
181
|
name: minitest-focus
|
|
154
182
|
requirement: !ruby/object:Gem::Requirement
|
|
@@ -318,6 +346,7 @@ files:
|
|
|
318
346
|
- lib/graphql-docs/layouts/graphql_mutations.html
|
|
319
347
|
- lib/graphql-docs/layouts/graphql_objects.html
|
|
320
348
|
- lib/graphql-docs/layouts/graphql_operations.html
|
|
349
|
+
- lib/graphql-docs/layouts/graphql_queries.html
|
|
321
350
|
- lib/graphql-docs/layouts/graphql_scalars.html
|
|
322
351
|
- lib/graphql-docs/layouts/graphql_unions.html
|
|
323
352
|
- lib/graphql-docs/layouts/includes/arguments.html
|
|
@@ -348,14 +377,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
|
|
|
348
377
|
requirements:
|
|
349
378
|
- - ">="
|
|
350
379
|
- !ruby/object:Gem::Version
|
|
351
|
-
version:
|
|
380
|
+
version: '3.1'
|
|
352
381
|
required_rubygems_version: !ruby/object:Gem::Requirement
|
|
353
382
|
requirements:
|
|
354
383
|
- - ">="
|
|
355
384
|
- !ruby/object:Gem::Version
|
|
356
385
|
version: '0'
|
|
357
386
|
requirements: []
|
|
358
|
-
rubygems_version: 3.
|
|
387
|
+
rubygems_version: 3.5.16
|
|
359
388
|
signing_key:
|
|
360
389
|
specification_version: 4
|
|
361
390
|
summary: Easily generate beautiful documentation from your GraphQL schema.
|