Merge branch 'cguitarte-master-patch-8215' into 'master'

Explain generate GraphQL schema and how to edit

See merge request https://gitlab.com/gitlab-org/gitlab/-/merge_requests/149461



Merged-by: Peter Leitzen <pleitzen@gitlab.com>
Approved-by: Amy Qualls <aqualls@gitlab.com>
Approved-by: Kati Paizee <kpaizee@gitlab.com>
Approved-by: Peter Leitzen <pleitzen@gitlab.com>
Reviewed-by: Kati Paizee <kpaizee@gitlab.com>
Co-authored-by: Kati Paizee <kpaizee@gitlab.com>
Co-authored-by: Amy Qualls <aqualls@gitlab.com>
Co-authored-by: Christopher Guitarte <cguitarte@gitlab.com>

doc/api/graphql/reference/index.md

@@ -8,6 +8,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w
   This documentation is auto generated by a script.
   Please do not edit this file directly.
+  To edit the introductory text, modify `tooling/graphql/docs/templates/default.md.haml`.
+
   Run `bundle exec rake gitlab:graphql:compile_docs`
   or check the `compile_docs` task in `lib/tasks/gitlab/graphql.rake`.
 -->
@@ -16,7 +18,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 This documentation is self-generated based on GitLab current GraphQL schema.
-The API can be explored using the [interactive GraphQL explorer](../index.md#interactive-graphql-explorer).
+The API can be explored using the [interactive GraphQL explorer](../index.md#interactive-graphql-explorer). Developers can also [generate a machine-readable GraphQL schema in IDL and JSON formats](../../../development/rake_tasks.md#update-machine-readable-schema-files).
 Each table below documents a GraphQL type. Types match loosely to models, but not all
 fields and methods on a model are available via GraphQL.

tooling/graphql/docs/helper.rb

@@ -64,6 +64,8 @@ def auto_generated_comment
               This documentation is auto generated by a script.
               Please do not edit this file directly.
 
+              To edit the introductory text, modify `tooling/graphql/docs/templates/default.md.haml`.
+
               Run `bundle exec rake gitlab:graphql:compile_docs`
               or check the `compile_docs` task in `lib/tasks/gitlab/graphql.rake`.
             -->

tooling/graphql/docs/templates/default.md.haml

@@ -7,7 +7,7 @@
 
   This documentation is self-generated based on GitLab current GraphQL schema.
 
-  The API can be explored using the [interactive GraphQL explorer](../index.md#interactive-graphql-explorer).
+  The API can be explored using the [interactive GraphQL explorer](../index.md#interactive-graphql-explorer). Developers can also [generate a machine-readable GraphQL schema in IDL and JSON formats](../../../development/rake_tasks.md#update-machine-readable-schema-files).
 
   Each table below documents a GraphQL type. Types match loosely to models, but not all
   fields and methods on a model are available via GraphQL.