Migrate documentation to rdoc

.github/workflows/rdoc.yaml

@@ -0,0 +1,37 @@
+name: RDoc Documentation
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+permissions: {}
+
+env:
+  BUNDLE_WITH: docs
+
+jobs:
+  build:
+    name: Build and verify RDoc documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+      - name: Run strict documentation checks
+        run: bundle exec rake docs:check
+      - name: Check reproducible output
+        run: bundle exec rake docs:build_twice
+      - name: Check gem installation documentation
+        run: bundle exec ruby tool/docs/gem_install_check.rb
+      - name: Upload RDoc artifact
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: rdoc-site
+          path: |
+            tmp/rdoc-site
+            tmp/rdoc-api-compatibility.json
+            tmp/rdoc-link-report.json
+            tmp/rdoc-ref-report.json

.github/workflows/website.yaml

@@ -19,7 +19,7 @@ on:
 
 permissions: {}
 env:
-  BUNDLE_WITH: jekyll_plugins
+  BUNDLE_WITH: docs
 jobs:
   website:
     if: ${{ inputs.publish_website || github.ref_name }}
@@ -39,24 +39,32 @@ jobs:
         with:
           ruby-version: '3.1'
       - run: bundle install
-      - name: Build HTML, reindex
-        env:
-          ALGOLIA_API_KEY: ${{ secrets.ALGOLIA_API_KEY }}
+      - run: mkdir -p tmp
+      - name: Snapshot existing versioned API docs
+        run: bundle exec ruby tool/docs/publish_check.rb snapshot --pages gh-pages --snapshot tmp/gh-pages-api-doc-before.json
+      - name: Build RDoc site
         run: |
-          bundle exec rake site:fetch_latest site:build_doc site:update_search_index site:clean_html site:build_html
+          bundle exec rake docs:check
+          bundle exec rake docs:build_twice
+          bundle exec ruby tool/docs/gem_install_check.rb
+          rsync -a --delete --exclude '.git' --exclude 'api-doc' tmp/rdoc-site/ gh-pages/
+          touch gh-pages/.nojekyll
+      - name: Verify versioned API docs were preserved
+        run: bundle exec ruby tool/docs/publish_check.rb verify --pages gh-pages --snapshot tmp/gh-pages-api-doc-before.json
       - name: Commit changes as last committer
         run: |
-          git config --global user.name "$(git log --format="%aN" -n 1)"
-          git config --global user.email "$(git log --format="%aE" -n 1)"
-          bundle exec rake site:commit_changes
+          git -C gh-pages config user.name "$(git log --format="%aN" -n 1)"
+          git -C gh-pages config user.email "$(git log --format="%aE" -n 1)"
+          git -C gh-pages add -A
+          git -C gh-pages commit --allow-empty -m "Update documentation site"
       - name: Deploy to GitHub pages via gh-pages branch
         uses: peaceiris/actions-gh-pages@84c30a85c19949d7eee79c4ff27748b70285e453 # v4.1.0
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./gh-pages
   api_docs:
     needs: website
-    if: ${{ inputs.publish_version || github.ref_name }}
+    if: ${{ inputs.publish_version || startsWith(github.ref, 'refs/tags/v') }}
     permissions:
       contents: write
     name: Publish API Docs
@@ -65,7 +73,7 @@ jobs:
       - name: Checkout release tag
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
-          ref: ${{ env.GITHUB_REF }}
+          ref: ${{ github.ref }}
       - name: Checkout GitHub pages branch
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
@@ -75,18 +83,28 @@ jobs:
         with:
           ruby-version: '3.2'
       - run: bundle install
-      - name: Build API docs
+      - run: mkdir -p tmp
+      - name: Snapshot existing versioned API docs
+        run: bundle exec ruby tool/docs/publish_check.rb snapshot --pages gh-pages --snapshot tmp/gh-pages-api-doc-before.json
+      - name: Build versioned API docs
         env:
-          PUBLISH_VERSION: ${{ inputs.publish_version || env.GITHUB_REF }}
+          PUBLISH_VERSION: ${{ inputs.publish_version || github.ref_name }}
         run: |
-          bundle exec rake site:fetch_latest "apidocs:gen_version[${PUBLISH_VERSION}]"
+          VERSION="${PUBLISH_VERSION#v}"
+          bundle exec rake "docs:rdoc:build_version[${VERSION}]"
+          bundle exec ruby tool/docs/version_check.rb --root "tmp/rdoc-api/${VERSION}" --version "${VERSION}"
+          bundle exec ruby tool/docs/compatibility.rb --root "tmp/rdoc-api/${VERSION}" --rdoc "tmp/rdoc-api/${VERSION}/js/search_data.js" --strict
+          bundle exec ruby tool/docs/link_checker.rb --root "tmp/rdoc-api/${VERSION}" --allow-root-links --root-links gh-pages --strict
+          bundle exec ruby tool/docs/rdoc_ref_checker.rb --root "tmp/rdoc-api/${VERSION}"
+          mkdir -p "gh-pages/api-doc/${VERSION}"
+          rsync -a --delete "tmp/rdoc-api/${VERSION}/" "gh-pages/api-doc/${VERSION}/"
+          bundle exec ruby tool/docs/publish_check.rb verify --pages gh-pages --snapshot tmp/gh-pages-api-doc-before.json --allow-version "${VERSION}" --expected-version "${VERSION}"
       - name: Commit changes as rmosolgo
         run: |
           git config --global user.name rmosolgo
           git config --global user.email rdmosolgo@gmail.com
-          git status
-          bundle exec rake site:commit_changes
-          git status
+          git -C gh-pages add -A
+          git -C gh-pages commit --allow-empty -m "Update API documentation"
       - name: Deploy to GitHub pages via gh-pages branch
         uses: peaceiris/actions-gh-pages@84c30a85c19949d7eee79c4ff27748b70285e453 # v4.1.0
         with:

.rdoc_options

@@ -0,0 +1,4 @@
+---
+markup: markdown
+main_page: readme.md
+title: GraphQL Ruby API Documentation

Gemfile

@@ -13,10 +13,6 @@ if RUBY_VERSION >= "3.2.0"
   gem "minitest-mock"
 end
 
-# Website tasks opt in to these dependencies via BUNDLE_WITH=jekyll_plugins.
-group :jekyll_plugins, optional: true do
-  gem 'jekyll'
-  gem 'jekyll-sass-converter', '~> 2.2'
-  gem 'jekyll-algolia', '~> 1.0'
-  gem 'jekyll-redirect-from'
+group :docs, optional: true do
+  gem "rdoc", "~> 7.2"
 end

Rakefile

@@ -3,7 +3,6 @@ require "bundler/gem_helper"
 Bundler::GemHelper.install_tasks
 
 require "rake/testtask"
-require_relative "guides/_tasks/site"
 require_relative "lib/graphql/rake_task/validate"
 require 'rake/extensiontask'
 
@@ -19,8 +18,17 @@ Rake::TestTask.new do |t|
     end
   end
 
+  exclude_docs = begin
+    require "rdoc"
+    require "rdoc/generator/aliki"
+    false
+  rescue LoadError
+    true
+  end
+
   t.test_files = FileList.new("spec/**/*_spec.rb") do |fl|
     fl.exclude(*exclude_integrations.map { |int| "spec/integration/#{int}/**/*" })
+    fl.exclude("spec/docs/**/*") if exclude_docs
   end
 
   # After 2.7, there were not warnings for uninitialized ivars anymore
@@ -236,5 +244,70 @@ task :move_binary do
   `mv graphql-c_parser/lib/*.bundle graphql-c_parser/lib/graphql`
 end
 
+namespace :docs do
+  desc "Build the RDoc/Aliki documentation site"
+  task build: "docs:rdoc:build"
+
+  desc "Build and run documentation quality checks"
+  task check: "docs:rdoc:build" do
+    ruby "tool/docs/check.rb"
+    ruby "tool/docs/type_signatures.rb", "--check"
+    ruby "tool/docs/migrate_guides.rb", "--check"
+    ruby "tool/docs/guide_audit.rb"
+    ruby "tool/docs/compatibility.rb", "--root", "tmp/rdoc-site", "--rdoc", "tmp/rdoc-site/js/search_data.js", "--baseline", "docs/yard_api_baseline.yml", "--strict", "--json", "tmp/rdoc-api-compatibility.json"
+    ruby "tool/docs/link_checker.rb", "--root", "tmp/rdoc-site", "--strict", "--json", "tmp/rdoc-link-report.json"
+    ruby "tool/docs/rdoc_ref_checker.rb", "--root", "tmp/rdoc-site", "--json", "tmp/rdoc-ref-report.json"
+    sh "node tool/docs/assets/graphql_highlighter_test.js"
+  end
+
+  desc "Build the documentation twice and compare generated files"
+  task :build_twice do
+    require_relative "tool/docs/build"
+    require "digest"
+    require "fileutils"
+    require "pathname"
+    builder = GraphQLDocs::Build.new
+    first = builder.build_site(output: "tmp/rdoc-site-first")
+    second = builder.build_site(output: "tmp/rdoc-site-second")
+    digest = lambda do |root|
+      Dir[File.join(root, "**", "*")].select { |path| File.file?(path) }.sort.to_h do |path|
+        [Pathname.new(path).relative_path_from(Pathname.new(root)).to_s, Digest::SHA256.file(path).hexdigest]
+      end
+    end
+    raise "RDoc output is not reproducible" unless digest.call(first) == digest.call(second)
+    puts "RDoc output is reproducible"
+  ensure
+    FileUtils.rm_rf("tmp/rdoc-site-first")
+    FileUtils.rm_rf("tmp/rdoc-site-second")
+  end
+
+  namespace :rdoc do
+    desc "Build the shadow RDoc/Aliki documentation site"
+    task :build do
+      require_relative "tool/docs/build"
+      GraphQLDocs::Build.new.build_site
+    end
+
+    desc "Build versioned RDoc/Aliki API documentation"
+    task :build_version, [:version] do |_task, args|
+      require_relative "tool/docs/build"
+      version = args[:version] || ENV["GRAPHQL_VERSION"] || raise(ArgumentError, "A version is required")
+      GraphQLDocs::Build.new.build_version(version)
+    end
+
+    desc "Build the shadow RDoc site and serve it locally"
+    task :serve => :build do
+      require "webrick"
+      server = WEBrick::HTTPServer.new(
+        Port: Integer(ENV.fetch("PORT", "8808")),
+        DocumentRoot: File.expand_path("tmp/rdoc-site"),
+      )
+      trap("INT") { server.shutdown }
+      puts "Serving RDoc documentation at http://127.0.0.1:#{server.config[:Port]}"
+      server.start
+    end
+  end
+end
+
 desc "Build the C Extension"
 task build_ext: [:build_c_lexer, :build_yacc_parser, "compile:graphql_c_parser_ext", :move_binary]