Merge branch '30019-warn-about-stale-graphql-docs' into 'master'

Add test for stale GraphQL docs to CI

Closes #30019

See merge request gitlab-org/gitlab!18549

.gitlab/ci/docs.gitlab-ci.yml

@@ -67,3 +67,18 @@ docs lint:
     - bundle exec nanoc check internal_links
     # Check the internal anchor links
     - bundle exec nanoc check internal_anchors
+
+graphql-docs-verify:
+  extends:
+    - .default-tags
+    - .default-retry
+    - .default-cache
+    - .default-only
+    - .default-before_script
+    - .only-graphql-changes
+  variables:
+    SETUP_DB: "false"
+  stage: test
+  needs: ["setup-test-env"]
+  script:
+    - bundle exec rake gitlab:graphql:check_docs

.gitlab/ci/global.gitlab-ci.yml

@@ -71,6 +71,12 @@
       - "doc/**/*"
       - ".markdownlint.json"
 
+.only-graphql-changes:
+  only:
+    changes:
+      - "{,ee/}app/graphql/**/*"
+      - "{,ee/}lib/gitlab/graphql/**/*"
+
 .only-code-qa-changes:
   only:
     changes:

doc/development/pipelines.md

@@ -115,6 +115,7 @@ from a commit or MR by extending from the following CI definitions:
 - `.only-qa-changes`: Allows a job to only be created upon QA-related changes.
 - `.only-docs-changes`: Allows a job to only be created upon docs-related changes.
 - `.only-code-qa-changes`: Allows a job to only be created upon code-related or QA-related changes.
+- `.only-graphql-changes`: Allows a job to only be created upon graphql-related changes.
 
 **See <https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/global.gitlab-ci.yml>
 for the list of exact patterns.**
@@ -175,6 +176,7 @@ subgraph "`test` stage"
     db:* --> |needs| A;
     gitlab:setup --> |needs| A;
     downtime_check --> |needs and depends on| A;
+    graphql-docs-verify --> |needs| A;
     end
 
 subgraph "`review-prepare` stage"

lib/gitlab/graphql/docs/renderer.rb

@@ -23,15 +23,12 @@ module Gitlab
           @parsed_schema = GraphQLDocs::Parser.new(schema, {}).parse
         end
 
-        def render
-          contents = @layout.render(self)
-
-          write_file(contents)
+        def contents
+          # Render and remove an extra trailing new line
+          @contents ||= @layout.render(self).sub!(/\n(?=\Z)/, '')
         end
 
-        private
-
-        def write_file(contents)
+        def write
           filename = File.join(@output_dir, 'index.md')
 
           FileUtils.mkdir_p(@output_dir)

lib/gitlab/graphql/docs/templates/default.md.haml

@@ -20,6 +20,3 @@
     - type[:fields].each do |field|
       = "| `#{field[:name]}` | #{render_field_type(field[:type][:info])} | #{field[:description]} |"
     \
-
-
-

lib/tasks/gitlab/graphql.rake

@@ -11,10 +11,28 @@ namespace :gitlab do
     task compile_docs: :environment do
       renderer = Gitlab::Graphql::Docs::Renderer.new(GitlabSchema.graphql_definition, render_options)
 
-      renderer.render
+      renderer.write
 
       puts "Documentation compiled."
     end
+
+    desc 'GitLab | Check if GraphQL docs are up to date'
+    task check_docs: :environment do
+      renderer = Gitlab::Graphql::Docs::Renderer.new(GitlabSchema.graphql_definition, render_options)
+
+      doc = File.read(Rails.root.join(OUTPUT_DIR, 'index.md'))
+
+      if doc == renderer.contents
+        puts "GraphQL documentation is up to date"
+      else
+        puts '#' * 10
+        puts '#'
+        puts '# GraphQL documentation is outdated! Please update it by running `bundle exec rake gitlab:graphql:compile_docs`.'
+        puts '#'
+        puts '#' * 10
+        abort
+      end
+    end
   end
 end