graphql-docs 4.0.0 → 5.0.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/CHANGELOG.md +10 -1
- data/README.md +41 -40
- data/exe/graphql-docs +6 -0
- data/graphql-docs.gemspec +2 -2
- data/lib/graphql-docs/generator.rb +4 -2
- data/lib/graphql-docs/helpers.rb +1 -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 +1 -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/parser.rb +4 -0
- data/lib/graphql-docs/renderer.rb +1 -0
- data/lib/graphql-docs/version.rb +1 -1
- metadata +7 -7
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: cbf28a678c378ebc2d54f6e5b7b24a05bd3eb577f144b9042fe11c4e7f34bd13
|
4
|
+
data.tar.gz: 993ad8805892c0544128baabec9dfd4f5bfb1cf16fccbe5cc43c3373036fcbbd
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 94e80febfa9d2c367182afd21b6a0d3e1206ec3d076a6b774ecfb96308648e4e582e818d1ac4f0b0734aaad514e46edac8a50f9ecb6baddf1370790e5eee7f38
|
7
|
+
data.tar.gz: 549077a6761dd67e983ab2c6bb402d5d67cfecafde214ddc57a7580439012eeb6a68ae6f0ff2091076d56eb64449aae9c055d87dc6e8a9da3fec081f51806d76
|
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.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/CHANGELOG.md
CHANGED
@@ -4,6 +4,15 @@ A concise overview of the public-facing changes to the gem from version to versi
|
|
4
4
|
|
5
5
|
## Unreleased
|
6
6
|
|
7
|
+
## v5.0.0 - 2024-07-03
|
8
|
+
|
9
|
+
- **breaking**: The graphql gem 2.2.0+ breaks some of the parsing and displaying of comments from a GraphQL schema file
|
10
|
+
- **breaking**: Ruby 2.6, 2.7, 3.0 are no longer supported as they are End of Life (EOL)
|
11
|
+
- feat: CLI version flag: `graphql-docs --version` / `graphql-docs -v`
|
12
|
+
- fix: CLI now works outside of a Bundler project
|
13
|
+
- fix: test suite
|
14
|
+
- chore: switch to sess-embedded gem for more maintained dependency
|
15
|
+
|
7
16
|
## v4.0.0 - 2023-01-26
|
8
17
|
|
9
18
|
- **Breaking change**: drop support for Ruby 2.5 and earlier
|
@@ -12,7 +21,7 @@ A concise overview of the public-facing changes to the gem from version to versi
|
|
12
21
|
- Fixes:
|
13
22
|
- Upgrade commonmarker to latest ver to address security vulnerabilities
|
14
23
|
- commonmarker pinned to version without security vulnerability
|
15
|
-
- Chores
|
24
|
+
- Chores:
|
16
25
|
- Dev env refresh
|
17
26
|
|
18
27
|
## 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,7 +43,7 @@ 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
47
|
|
48
48
|
spec.add_development_dependency 'html-proofer', '~> 3.4'
|
49
49
|
spec.add_development_dependency 'minitest', '~> 5.0'
|
@@ -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
|
@@ -84,8 +86,8 @@ module GraphQLDocs
|
|
84
86
|
assets_dir = File.join(File.dirname(__FILE__), 'layouts', 'assets')
|
85
87
|
FileUtils.mkdir_p(File.join(@options[:output_dir], 'assets'))
|
86
88
|
|
87
|
-
|
88
|
-
|
89
|
+
css = Sass.compile(File.join(assets_dir, 'css', 'screen.scss')).css
|
90
|
+
File.write(File.join(@options[:output_dir], 'assets', 'style.css'), css)
|
89
91
|
|
90
92
|
FileUtils.cp_r(File.join(assets_dir, 'images'), File.join(@options[:output_dir], 'assets'))
|
91
93
|
FileUtils.cp_r(File.join(assets_dir, 'webfonts'), File.join(@options[:output_dir], 'assets'))
|
data/lib/graphql-docs/helpers.rb
CHANGED
@@ -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,4 @@
|
|
1
1
|
---
|
2
2
|
title: Queries
|
3
3
|
---
|
4
|
-
Every GraphQL schema has a root type for both queries and mutations. The [query type](
|
4
|
+
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.
|
@@ -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).
|
data/lib/graphql-docs/parser.rb
CHANGED
@@ -177,6 +177,10 @@ module GraphQLDocs
|
|
177
177
|
h[:description] = arg.description
|
178
178
|
h[:type] = generate_type(arg.type)
|
179
179
|
h[:default_value] = arg.default_value if arg.default_value?
|
180
|
+
if arg.respond_to?(:deprecation_reason) && arg.deprecation_reason
|
181
|
+
h[:is_deprecated] = true
|
182
|
+
h[:deprecation_reason] = arg.deprecation_reason
|
183
|
+
end
|
180
184
|
hash[:arguments] << h
|
181
185
|
end
|
182
186
|
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.0.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-07-03 00:00:00.000000000 Z
|
13
13
|
dependencies:
|
14
14
|
- !ruby/object:Gem::Dependency
|
15
15
|
name: graphql
|
@@ -108,19 +108,19 @@ 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
124
|
- !ruby/object:Gem::Dependency
|
125
125
|
name: html-proofer
|
126
126
|
requirement: !ruby/object:Gem::Requirement
|
@@ -348,14 +348,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
|
|
348
348
|
requirements:
|
349
349
|
- - ">="
|
350
350
|
- !ruby/object:Gem::Version
|
351
|
-
version:
|
351
|
+
version: '3.1'
|
352
352
|
required_rubygems_version: !ruby/object:Gem::Requirement
|
353
353
|
requirements:
|
354
354
|
- - ">="
|
355
355
|
- !ruby/object:Gem::Version
|
356
356
|
version: '0'
|
357
357
|
requirements: []
|
358
|
-
rubygems_version: 3.
|
358
|
+
rubygems_version: 3.5.7
|
359
359
|
signing_key:
|
360
360
|
specification_version: 4
|
361
361
|
summary: Easily generate beautiful documentation from your GraphQL schema.
|