{"id":13566075,"url":"https://github.com/brettchalupa/graphql-docs","last_synced_at":"2025-05-13T21:04:23.068Z","repository":{"id":17222522,"uuid":"81388642","full_name":"brettchalupa/graphql-docs","owner":"brettchalupa","description":"Easily generate beautiful documentation from your GraphQL schema.","archived":false,"fork":false,"pushed_at":"2025-02-11T01:48:46.000Z","size":3077,"stargazers_count":518,"open_issues_count":26,"forks_count":67,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-04-28T13:58:46.544Z","etag":null,"topics":["documentation","good-first-issue","graphql","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brettchalupa.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-02-08T23:53:11.000Z","updated_at":"2025-03-15T23:00:18.000Z","dependencies_parsed_at":"2024-07-30T15:18:20.444Z","dependency_job_id":"4691eee2-6d52-4894-afa7-6d243447bcfb","html_url":"https://github.com/brettchalupa/graphql-docs","commit_stats":{"total_commits":279,"total_committers":19,"mean_commits":14.68421052631579,"dds":0.4731182795698925,"last_synced_commit":"a132904b124b0c6fd4ec77cd6a83a5376a8e038d"},"previous_names":["gjtorikian/graphql-docs"],"tags_count":52,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brettchalupa%2Fgraphql-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brettchalupa%2Fgraphql-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brettchalupa%2Fgraphql-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brettchalupa%2Fgraphql-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brettchalupa","download_url":"https://codeload.github.com/brettchalupa/graphql-docs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254028374,"owners_count":22002241,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","good-first-issue","graphql","ruby"],"created_at":"2024-08-01T13:02:01.561Z","updated_at":"2025-05-13T21:04:23.049Z","avatar_url":"https://github.com/brettchalupa.png","language":"Ruby","readme":"# GraphQLDocs\n\nRuby library and CLI for easily generating beautiful documentation from your GraphQL schema.\n\n![sample](https://cloud.githubusercontent.com/assets/64050/23438604/6a23add0-fdc7-11e6-8852-ef41e8451033.png)\n\n## Installation\n\nAdd the gem to your project with this command:\n\n```console\nbundle add graphql-docs\n```\n\nOr install it yourself as:\n\n```console\ngem install graphql-docs\n```\n\n## Usage\n\nGraphQLDocs 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:\n\n```ruby\n# pass in a filename\nGraphQLDocs.build(filename: filename)\n\n# or pass in a string\nGraphQLDocs.build(schema: contents)\n\n# or a schema class\nschema = GraphQL::Schema.define do\n query query_type\nend\nGraphQLDocs.build(schema: schema)\n```\n\nGraphQLDocs also has a simplified CLI (`graphql-docs`) that gets installed with the gem:\n\n```console\ngraphql-docs schema.graphql\n```\n\nThat will generate the output in the `output` dir.\n\nSee all of the supported CLI options with:\n\n```console\ngraphql-docs -h\n```\n\n## Breakdown\n\nThere are several phases going on the single `GraphQLDocs.build` call:\n\n- The GraphQL IDL file is read (if you passed `filename`) through `GraphQL::Client` (or simply read if you passed a string through `schema`).\n- `GraphQL::Parser` manipulates the IDL into a slightly saner format.\n- `GraphQL::Generator` takes that saner format and begins the process of applying items to the HTML templates.\n- `GraphQL::Renderer` technically runs as part of the generation phase. It passes the contents of each page and converts it into HTML.\n\nIf you wanted to, you could break these calls up individually. For example:\n\n```ruby\noptions = {}\noptions[:filename] = \"#{File.dirname(__FILE__)}/../data/graphql/schema.idl\"\noptions[:renderer] = MySuperCoolRenderer\n\noptions = GraphQLDocs::Configuration::GRAPHQLDOCS_DEFAULTS.merge(options)\n\nresponse = File.read(options[:filename])\n\nparser = GraphQLDocs::Parser.new(response, options)\nparsed_schema = parser.parse\n\ngenerator = GraphQLDocs::Generator.new(parsed_schema, options)\n\ngenerator.generate\n```\n\n## Generating output\n\nBy 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.\n\nIt 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:\n\n- `initialize` - Takes two arguments, the parsed `schema` and the configuration `options`.\n- `render` Takes the contents of a template page. It also takes two optional kwargs, the GraphQL `type` and its `name`. For example:\n\n```ruby\nclass CustomRenderer\n def initialize(parsed_schema, options)\n @parsed_schema = parsed_schema\n @options = options\n end\n\n def render(contents, type: nil, name: nil)\n contents.sub(/Repository/i, '\u003cstrong\u003eMeow Woof!\u003c/strong\u003e')\n\n opts[:content] = contents\n @graphql_default_layout.result(OpenStruct.new(opts).instance_eval { binding })\n end\nend\n\noptions[:filename] = 'location/to/sw-api.graphql'\noptions[:renderer] = CustomRenderer\n\nGraphQLDocs.build(options)\n```\n\nIf your `render` method returns `nil`, the `Generator` will not attempt to write any HTML file.\n\n### Templates\n\nThe layouts for the individual GraphQL pages are ERB templates, but you can also use ERB templates for your static landing pages.\n\nIf you want to add additional variables for your landing pages, you can add define a `variables` hash within the `landing_pages` option.\n\n### Helper methods\n\nIn your ERB layouts, there are several helper methods you can use. The helper methods are:\n\n- `slugify(str)` - This slugifies the given string.\n- `include(filename, opts)` - This embeds a template from your `includes` folder, passing along the local options provided.\n- `markdownify(string)` - This converts a string into HTML via CommonMarker.\n- `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.\n\nTo call these methods within templates, you must use the dot notation, such as `\u003c%= slugify.(text) %\u003e`.\n\n## Configuration\n\nThe following options are available:\n\n| Option | Description | Default |\n| :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `filename` | The location of your schema's IDL file. | `nil` |\n| `schema` | A string representing a schema IDL file. | `nil` |\n| `output_dir` | The location of the output HTML. | `./output/` |\n| `use_default_styles` | Indicates if you want to use the default styles. | `true` |\n| `base_url` | Indicates the base URL to prepend for assets and links. | `\"\"` |\n| `delete_output` | Deletes `output_dir` before generating content. | `false` |\n| `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. |\n| `renderer` | The rendering class to use. | `GraphQLDocs::Renderer` |\n| `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/_. |\n| `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/_. |\n| `classes` | Additional class names you can provide to certain elements. | The full list is available in _lib/graphql-docs/configuration.rb_. |\n| `notices` | A proc used to add notices to schema members. See _Customizing Notices_ section below. | `nil` |\n\n### Customizing Notices\n\nA notice is a block of CommonMark text that optionally has a title which is displayed above a schema member's description. The\nlook of a notice block can be controlled by specifying a custom class for it and then styled via CSS.\n\nThe `notices` option allows you to customize the notices that appear for a specific schema member using a proc.\n\nThe proc will be called for each schema member and needs to return an array of notices or an empty array if there are none.\n\nA `notice` has the following options:\n\n| Option | Description |\n| :------------ | :-------------------------------------------------------- |\n| `body` | CommonMark body of the notice |\n| `title` | Optional title of the notice |\n| `class` | Optional CSS class for the wrapper `\u003cdiv\u003e` of the notice |\n| `title_class` | Optional CSS class for the `\u003cspan\u003e` of the notice's title |\n\nExample of a `notices` proc that adds a notice to the `TeamDiscussion` type:\n\n```ruby\noptions[:notices] = -\u003e(schema_member_path) {\n notices = []\n\n if schema_member_path == \"TeamDiscussion\"\n notices \u003c\u003c {\n class: \"preview-notice\",\n body: \"Available via the [Team Discussion](/previews/team-discussion) preview.\",\n }\n end\n\n notices\n}\n```\n\nThe format of `schema_member_path` is a dot delimited path to the schema member. For example:\n\n```ruby\n\"Author\", # an object\n\"ExtraInfo\" # an interface,\n\"Author.socialSecurityNumber\" # a field\n\"Book.author.includeMiddleInitial\" # an argument\n\"Likeable\" # a union,\n\"Cover\" # an enum\n\"Cover.DIGITAL\" # an enum value\n\"BookOrder\" # an input object\n\"Mutation.addLike\" # a mutation\n```\n\n## Supported Ruby Versions\n\nThe gem officially supports **Ruby 3.1 and newer**.\n\nAny dropping of Ruby version support is considered a breaking change and means a major release for the gem.\n\n## Upgrading\n\nThis project aims to strictly follow [Semantic Versioning](https://semver.org/).\nMinor and patch level updates can be done with pretty high confidence that your usage won't break.\n\nReview the\n[Changelog](https://github.com/brettchalupa/graphql-docs/blob/main/CHANGELOG.md)\nfor detailed changes for each release. The intent is to make upgrading as\npainless as possible.\n\n## Roadmap\n\nUpcoming work for the project is organized publicly via [GitHub\nProjects](https://github.com/users/brettchalupa/projects/7/views/1).\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run\n`bin/rake test` to run the tests. You can also run `bin/console` for\nan interactive prompt that will allow you to experiment.\n\n### Releasing a new version of the gem\n\n1. Update CHANGELOG.md\n2. Bump the version in `lib/graphql-docs/version.rb`\n3. Make a commit and tag it with `git commit -a vX.X.X`\n4. Push the commit and tags to GitHub: `git push origin main \u0026\u0026 git push --tags`\n5. Build the gem: `gem build`\n6. Push the gem to RubyGems.org: `gem push graphql-docs-X.X.X.gem`\n\n## Sample Site\n\nClone this repository and run:\n\n```\nbin/rake sample:generate\n```\n\nto see some sample output in the `output` dir.\n\nBoot up a server to view it:\n\n```\nbin/rake sample:serve\n```\n\n## Credits\n\nOriginally built by [gjtorikian](https://github.com/gjtorikian). Actively maintained by [brettchalupa](https://github.com/brettchalupa).\n","funding_links":[],"categories":["Ruby","Documentation Types"],"sub_categories":["API Documentation"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrettchalupa%2Fgraphql-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrettchalupa%2Fgraphql-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrettchalupa%2Fgraphql-docs/lists"}