feat: Move away from github-pages gem and add ruby 4 support for docs (#2588)

This PR reworks the doc page deployment by removing the github pages gem
and deploying using a github actions workflow. This was done to enable
support for ruby 4, which is unsupported by github pages. As a result of
the docs being deployed by github actions rather than pages, the
deployment process for docs has changed, this PR also has an update to
the contribution docs to reflect these changes. The github action
workflow is set to deploy docs when there is a push to the docs branch.

This PR also adds some plugins for Jekyll. These were ones that github
pages added automatically, now that we have removed github pages, thee
plugins are included here instead.

Once this PR is merged, the "Pages" settings will need to be updated.
The build and deployment source will need to be changed to github
actions.

---------

Co-authored-by: Rex P <106129829+another-rex@users.noreply.github.com>
Co-authored-by: Joey L <joeylauy@google.com>

Author: 3 people

.github/workflows/docs-deploy.yml

@@ -0,0 +1,66 @@
+name: Deploy Jekyll site to Pages
+
+on:
+  push:
+    branches: [docs]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+# Restrict jobs in this workflow to have no permissions by default; permissions
+# should be granted per job as needed using a dedicated `permissions` block
+permissions: {}
+
+jobs:
+  # Build job
+  build:
+    permissions:
+      contents: read
+    env: # $BUNDLE_GEMFILE must be set at the job level, so it is set for all steps
+      BUNDLE_GEMFILE: ${{ github.workspace }}/docs/Gemfile
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./docs
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@19a43a6a2428d455dbd1b85344698725179c9d8c # v1.289.0
+        with:
+          ruby-version: "4" # Not needed with a .ruby-version file
+          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+          cache-version: 0 # Increment this number if you need to re-download cached gems
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0
+      - name: Build with Jekyll
+        run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
+        env:
+          JEKYLL_ENV: production
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
+        with:
+          path: ./docs/_site
+
+  # Deployment job
+  deploy:
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

CONTRIBUTING.md

@@ -174,11 +174,11 @@ Please follow these steps to successfully contribute documentation.
 3. Preview the changes by spinning up a GitHub page for your fork, building from your working branch.
    <!-- markdown-link-check-disable-next-line -->
    - On your fork, go to the settings tab and then the GitHub page settings. Sample URL: https://github.com/{your-github-profile}/osv-scanner/settings/pages
-   - Under "Build and deployment" select "Deploy from a branch"
-   - Set the branch to your working branch
-   - Set the github page to build from the "/docs" folder
-   - Hit save and wait for your site to build
+   - Under "Build and deployment" select "Github Actions"
+   - Add your working branch to the on push branches (line 5) in the "docs-deploy.yml" file, this can be found in the ".github/workflows" directory
+   - Push your commit and wait for the pages to build
    - Once it is ready, click the link and preview the docs
+   - If the pages were built successfully, remove your branch from the "docs-deploy.yml" workflow
 
 ![Image shows the UI settings for building the GitHub page, which is described in step 3 of the contributing documentation instructions.](docs/images/github-page.png)
 

docs/Gemfile

@@ -1,4 +1,4 @@
-ruby "~> 3"
+ruby "~> 4"
 
 source "https://rubygems.org"
 # Hello! This is where you manage which Jekyll version is used to run.
@@ -9,15 +9,17 @@ source "https://rubygems.org"
 #
 # This will help ensure the proper Jekyll version is running.
 # Happy Jekylling!
-# gem "jekyll", "~> 4.3.2"
-# This is the default theme for new Jekyll sites. You may change this to anything you like.
-# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
-# uncomment the line below. To upgrade, run `bundle update github-pages`.
-gem "github-pages", "~> 232", group: :jekyll_plugins
-# If you have any plugins, put them here!
-group :jekyll_plugins do
-  gem "jekyll-feed", "~> 0.15"
-end
+gem "jekyll", "~> 4.3.2"
+gem "csv"
+gem "base64"
+gem "jekyll-feed", "~> 0.15"
+gem "jekyll-relative-links"
+gem "jekyll-optional-front-matter"
+gem "jekyll-readme-index"
+gem "jekyll-default-layout"
+gem "jekyll-titles-from-headings"
+gem "just-the-docs"
+gem "jekyll-github-metadata"
 
 # Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
 # and associated library.