Merge branch '29978-document-graphql-doc-rake-task' into 'master'

Document gitlab:graphql:compile_docs

See merge request gitlab-org/gitlab!18548

doc/development/api_graphql_styleguide.md

@@ -539,3 +539,8 @@ it 'returns a successful response' do
    expect(graphql_mutation_response(:merge_request_set_wip)['errors']).to be_empty
 end
 ```
+
+## Documentation
+
+For information on generating GraphQL documentation, see
+[Rake tasks related to GraphQL](rake_tasks.md#update-graphql-documentation).

doc/development/rake_tasks.md

@@ -220,3 +220,26 @@ bundle exec rake db:obsolete_ignored_columns
 ```
 
 Feel free to remove their definitions from their `ignored_columns` definitions.
+
+## Update GraphQL Documentation
+
+To generate GraphQL documentation based on the GitLab schema, run:
+
+```shell
+bundle exec rake gitlab:graphql:compile_docs
+```
+
+In its current state, the rake task:
+
+- Generates output for GraphQL objects.
+- Places the output at `docs/api/graphql/reference/index.md`.
+
+This uses some features from `graphql-docs` gem like its schema parser and helper methods.
+The docs generator code comes from our side giving us more flexibility, like using Haml templates and generating Markdown files.
+
+To edit the template used, please take a look at `lib/gitlab/graphql/docs/templates/default.md.haml`.
+The actual renderer is at `Gitlab::Graphql::Docs::Renderer`.
+
+`@parsed_schema` is an instance variable that the `graphql-docs` gem expects to have available.
+`Gitlab::Graphql::Docs::Helper` defines the `object` method we currently use. This is also where you should implement any
+new methods for new types you'd like to display.