graphql-docs 4.0.0 → 5.0.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/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.
|