Skip to content

Commit

Permalink
Merge pull request #152 from brettchalupa/v5.0.0-release
Browse files Browse the repository at this point in the history 
Prepared for v5.0.0 release
  • Loading branch information
@brettchalupa
brettchalupa authored Jul 3, 2024
2 parents 044ecfd + d983eb3 commit d3c9af2
Show file tree
Hide file tree
Showing 3 changed files with 44 additions and 41 deletions.
5 changes: 5 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,14 @@ A concise overview of the public-facing changes to the gem from version to versi

## Unreleased

## v5.0.0 - 2024-07-03

- **breaking**: The graphql gem 2.2.0+ breaks some of the parsing and displaying of comments from a GraphQL schema file
- **breaking**: Ruby 2.6, 2.7, 3.0 are no longer supported as they are End of Life (EOL)
- feat: CLI version flag: `graphql-docs --version` / `graphql-docs -v`
- fix: CLI now works outside of a Bundler project
- fix: test suite
- chore: switch to sess-embedded gem for more maintained dependency

## v4.0.0 - 2023-01-26

Expand Down
78 changes: 38 additions & 40 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,21 +8,21 @@ Ruby library and CLI for easily generating beautiful documentation from your Gra

Add the gem to your project with this command:

``` console
```console
bundle add graphql-docs
```

Or install it yourself as:

``` console
```console
gem install graphql-docs
```

## Usage

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:

``` ruby
```ruby
# pass in a filename
GraphQLDocs.build(filename: filename)

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

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

``` console
```console
graphql-docs schema.graphql
```

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

See all of the supported CLI options with:

``` console
```console
graphql-docs -h
```

## Breakdown

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

* The GraphQL IDL file is read (if you passed `filename`) through `GraphQL::Client` (or simply read if you passed a string through `schema`).
* `GraphQL::Parser` manipulates the IDL into a slightly saner format.
* `GraphQL::Generator` takes that saner format and begins the process of applying items to the HTML templates.
* `GraphQL::Renderer` technically runs as part of the generation phase. It passes the contents of each page and converts it into HTML.
- The GraphQL IDL file is read (if you passed `filename`) through `GraphQL::Client` (or simply read if you passed a string through `schema`).
- `GraphQL::Parser` manipulates the IDL into a slightly saner format.
- `GraphQL::Generator` takes that saner format and begins the process of applying items to the HTML templates.
- `GraphQL::Renderer` technically runs as part of the generation phase. It passes the contents of each page and converts it into HTML.

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

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

## Generating output

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

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:

* `initialize` - Takes two arguments, the parsed `schema` and the configuration `options`.
* `render` Takes the contents of a template page. It also takes two optional kwargs, the GraphQL `type` and its `name`. For example:
- `initialize` - Takes two arguments, the parsed `schema` and the configuration `options`.
- `render` Takes the contents of a template page. It also takes two optional kwargs, the GraphQL `type` and its `name`. For example:

``` ruby
```ruby
class CustomRenderer
def initialize(parsed_schema, options)
@parsed_schema = parsed_schema
Expand Down Expand Up @@ -120,31 +120,31 @@ If you want to add additional variables for your landing pages, you can add defi

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

* `slugify(str)` - This slugifies the given string.
* `include(filename, opts)` - This embeds a template from your `includes` folder, passing along the local options provided.
* `markdownify(string)` - This converts a string into HTML via CommonMarker.
* `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.
- `slugify(str)` - This slugifies the given string.
- `include(filename, opts)` - This embeds a template from your `includes` folder, passing along the local options provided.
- `markdownify(string)` - This converts a string into HTML via CommonMarker.
- `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.

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

## Configuration

The following options are available:

| Option | Description | Default |
| :----- | :---------- | :------ |
| `filename` | The location of your schema's IDL file. | `nil` |
| `schema` | A string representing a schema IDL file. | `nil` |
| `output_dir` | The location of the output HTML. | `./output/` |
| `use_default_styles` | Indicates if you want to use the default styles. | `true` |
| `base_url` | Indicates the base URL to prepend for assets and links. | `""` |
| `delete_output` | Deletes `output_dir` before generating content. | `false` |
| `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. |
| `renderer` | The rendering class to use. | `GraphQLDocs::Renderer`
| `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/_.
| `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/_.
| `classes` | Additional class names you can provide to certain elements. | The full list is available in _lib/graphql-docs/configuration.rb_.
| `notices` | A proc used to add notices to schema members. See *Customizing Notices* section below. | `nil` |
| Option | Description | Default |
| :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `filename` | The location of your schema's IDL file. | `nil` |
| `schema` | A string representing a schema IDL file. | `nil` |
| `output_dir` | The location of the output HTML. | `./output/` |
| `use_default_styles` | Indicates if you want to use the default styles. | `true` |
| `base_url` | Indicates the base URL to prepend for assets and links. | `""` |
| `delete_output` | Deletes `output_dir` before generating content. | `false` |
| `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. |
| `renderer` | The rendering class to use. | `GraphQLDocs::Renderer` |
| `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/_. |
| `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/_. |
| `classes` | Additional class names you can provide to certain elements. | The full list is available in _lib/graphql-docs/configuration.rb_. |
| `notices` | A proc used to add notices to schema members. See _Customizing Notices_ section below. | `nil` |

### Customizing Notices

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

A `notice` has the following options:

| Option | Description |
| :----- | :---------- |
| `body` | CommonMark body of the notice |
| `title` | Optional title of the notice |
| `class` | Optional CSS class for the wrapper `<div>` of the notice |
| Option | Description |
| :------------ | :-------------------------------------------------------- |
| `body` | CommonMark body of the notice |
| `title` | Optional title of the notice |
| `class` | Optional CSS class for the wrapper `<div>` of the notice |
| `title_class` | Optional CSS class for the `<span>` of the notice's title |

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

## Supported Ruby Versions

The gem officially supports **Ruby 2.7 and newer**.

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.
The gem officially supports **Ruby 3.1 and newer**.

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

Expand Down
2 changes: 1 addition & 1 deletion lib/graphql-docs/version.rb
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# frozen_string_literal: true

module GraphQLDocs
VERSION = '4.0.0'
VERSION = '5.0.0'
end

0 comments on commit d3c9af2

Please sign in to comment.