Skip to content

Commit d3c9af2

Browse files
brettchalupabrettchalupa
authored
Merge pull request #152 from brettchalupa/v5.0.0-release
Prepared for v5.0.0 release
2 parents 044ecfd + d983eb3 commit d3c9af2

File tree

3 files changed

+44
-41
lines changed

3 files changed

+44
-41
lines changed

‎CHANGELOG.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,14 @@ A concise overview of the public-facing changes to the gem from version to versi
44

55
## Unreleased
66

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)
711
- feat: CLI version flag: `graphql-docs --version` / `graphql-docs -v`
812
- fix: CLI now works outside of a Bundler project
913
- fix: test suite
14+
- chore: switch to sess-embedded gem for more maintained dependency
1015

1116
## v4.0.0 - 2023-01-26
1217

‎README.md‎

Lines changed: 38 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -8,21 +8,21 @@ Ruby library and CLI for easily generating beautiful documentation from your Gra
88

99
Add the gem to your project with this command:
1010

11-
``` console
11+
```console
1212
bundle add graphql-docs
1313
```
1414

1515
Or install it yourself as:
1616

17-
``` console
17+
```console
1818
gem install graphql-docs
1919
```
2020

2121
## Usage
2222

2323
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:
2424

25-
``` ruby
25+
```ruby
2626
# pass in a filename
2727
GraphQLDocs.build(filename: filename)
2828

@@ -38,30 +38,30 @@ GraphQLDocs.build(schema: schema)
3838

3939
GraphQLDocs also has a simplified CLI (`graphql-docs`) that gets installed with the gem:
4040

41-
``` console
41+
```console
4242
graphql-docs schema.graphql
4343
```
4444

4545
That will generate the output in the `output` dir.
4646

4747
See all of the supported CLI options with:
4848

49-
``` console
49+
```console
5050
graphql-docs -h
5151
```
5252

5353
## Breakdown
5454

5555
There are several phases going on the single `GraphQLDocs.build` call:
5656

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.
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.
6161

6262
If you wanted to, you could break these calls up individually. For example:
6363

64-
``` ruby
64+
```ruby
6565
options = {}
6666
options[:filename] = "#{File.dirname(__FILE__)}/../data/graphql/schema.idl"
6767
options[:renderer] = MySuperCoolRenderer
@@ -80,14 +80,14 @@ generator.generate
8080

8181
## Generating output
8282

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.
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.
8484

8585
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:
8686

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:
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:
8989

90-
``` ruby
90+
```ruby
9191
class CustomRenderer
9292
def initialize(parsed_schema, options)
9393
@parsed_schema = parsed_schema
@@ -120,31 +120,31 @@ If you want to add additional variables for your landing pages, you can add defi
120120

121121
In your ERB layouts, there are several helper methods you can use. The helper methods are:
122122

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.
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.
127127

128128
To call these methods within templates, you must use the dot notation, such as `<%= slugify.(text) %>`.
129129

130130
## Configuration
131131

132132
The following options are available:
133133

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` |
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` |
148148

149149
### Customizing Notices
150150

@@ -157,11 +157,11 @@ The proc will be called for each schema member and needs to return an array of n
157157

158158
A `notice` has the following options:
159159

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 |
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 |
165165
| `title_class` | Optional CSS class for the `<span>` of the notice's title |
166166

167167
Example of a `notices` proc that adds a notice to the `TeamDiscussion` type:
@@ -197,9 +197,7 @@ The format of `schema_member_path` is a dot delimited path to the schema member.
197197

198198
## Supported Ruby Versions
199199

200-
The gem officially supports **Ruby 2.7 and newer**.
201-
202-
A note about Ruby 2.6: It works, but it requires activesupport to be set to a version less than 7 due to it dropping Ruby 2.6 support. Ruby 2.6 is no longer tested on CI.
200+
The gem officially supports **Ruby 3.1 and newer**.
203201

204202
Any dropping of Ruby version support is considered a breaking change and means a major release for the gem.
205203

‎lib/graphql-docs/version.rb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# frozen_string_literal: true
22

33
module GraphQLDocs
4-
VERSION = '4.0.0'
4+
VERSION = '5.0.0'
55
end

0 commit comments

Comments
 (0)