graphql-docs 4.0.0 → 5.1.0
Sign up to get free protection for your applications and to get access to all the features.
- 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.
|