Add API documentation with GitHub Pages deployment

This adds automated deployment of a versioned API documentation landing
page using GitHub Pages. The landing page links to documentation hosted
on RubyDoc.info, the de facto standard documentation site for the Ruby
ecosystem. The landing page will update to reflect new releases.

Changes
-------

1. **Documentation generation script** (see `bin/generate-gh-pages.sh`)

    Copies and commits documentation files to the gh-pages branch. The
    script uses git worktrees to isolate the process from the main
    workspace.

    The script:

    - Creates the gh-pages branch as an orphan branch if it doesn't exist
    - Parses semantic versions from tag names, ignoring arbitrary
      prefixes (e.g., tags `1.2.3`, `v1.2.3`, and `release-1.2.3` all
      create `v1.2.3`)
    - Determines the latest version using semantic version sorting
    - Copies static Jekyll template files from `docs/` to the gh-pages
      root (for the latest version only)
    - Generates `docs/_data/versions.yml` with a list of all versions
      for the Jekyll templates to consume

2. **Jekyll template files** (see `docs/` directory)

    - `docs/_config.yml` - Jekyll configuration
    - `docs/index.md` - Landing page template that links to all versions
      on RubyDoc.info based on generated `docs/_data/versions.yml`
    - `docs/latest/index.html` - Redirect page template that redirects
      to the latest documentation on RubyDoc.info

3. **GitHub Actions workflow** (see `.github/workflows/release.yml`)

    Added a `publish_gh_pages` job that runs after the `publish_gem` job
    on release events. The job invokes the generation script with the
    release tag name, then pushes the updated gh-pages branch to deploy
    the documentation.

4. **CI validation** (see `.github/workflows/ci.yml`)

    Added a `yard` job that runs YARD validation with `--no-output`.
    This ensures YARD can successfully parse the codebase (without
    generating output), catching documentation issues early in CI.

5. **YARD dependencies** (see `Gemfile`)

    Added `yard` and `yard-sorbet` gems as development dependencies to
    support documentation validation in CI.

    YARD documentation is automatically generated and hosted by
    RubyDoc.info when the gem is published to RubyGems.org.

6. **Documentation links** (see `README.md` and `mcp.gemspec`)

    Added links to the published API documentation on RubyDoc.info in
    the README and gemspec metadata.

Documentation URL
-----------------

Custom documentation will be available at:
https://modelcontextprotocol.github.io/ruby-sdk/

RubyDoc.info documentation will be accessible at:
- https://rubydoc.info/gems/mcp (latest version)
- https://rubydoc.info/gems/mcp/1.2.3 (specific versions)

Co-Authored-By: Claude <noreply@anthropic.com>

.github/workflows/ci.yml

@@ -31,3 +31,14 @@ jobs:
           ruby-version: 3.2 # Specify the oldest supported Ruby version.
           bundler-cache: true
       - run: bundle exec rake rubocop
+
+  yard:
+    runs-on: ubuntu-latest
+    name: YARD Documentation
+    steps:
+      - uses: actions/checkout@v5
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.2 # Specify the oldest supported Ruby version.
+          bundler-cache: true
+      - run: bundle exec yard --no-output

.github/workflows/release.yml

@@ -23,3 +23,35 @@ jobs:
           bundler-cache: true
           ruby-version: 3.4
       - uses: rubygems/release-gem@v1
+
+  publish_gh_pages:
+    if: github.repository_owner == 'modelcontextprotocol'
+    name: Publish Documentation to GitHub Pages
+    runs-on: ubuntu-latest
+    needs: [publish_gem]
+
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0 # Fetch all history for all branches and tags
+
+      - name: Configure Git
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Get version tag
+        id: version
+        run: |
+          git fetch --tags
+          TAG=$(git describe --tags --exact-match HEAD)
+          echo "tag=${TAG}" >> $GITHUB_OUTPUT
+
+      - name: Generate GitHub Pages
+        run: ./bin/generate-gh-pages.sh ${{ steps.version.outputs.tag }}
+
+      - name: Push to gh-pages
+        run: git push origin gh-pages