Add RDoc documentation site for Rubydex APIs (#874)

## Problems

- Rubydex does not have generated API documentation that can be
published as a static site.
- The native extension exposes Ruby APIs from C, but most public
C-backed methods are not documented in a format RDoc can capture.

## Solutions

- Add RDoc configuration, a documentation rake task, and a GitHub Pages
workflow using the current RDoc commit.
- Include both Ruby and C extension sources in the generated site.
- Convert public C-backed API comments to RDoc `call-seq:` blocks with
RBS-ish return shapes.

<img width="80%" height="1364" alt="Screenshot 2026-06-24 at 21 07 02"
src="https://github.com/user-attachments/assets/89d1c023-9c30-41fb-9a7d-493b19be3964"
/>

(The `workspace_path` attribute's type label is weird but it's a RDoc
issue)

Author: st0012

.document

@@ -0,0 +1,5 @@
+README.md
+CONTRIBUTING.md
+docs/*.md
+lib/**/*.rb
+ext/rubydex/*.c

.github/workflows/pages.yml

@@ -0,0 +1,45 @@
+name: Deploy documentation to GitHub Pages
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: ${{ github.repository == 'Shopify/rubydex' }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@9eb537ca036ebaed86729dcb9309076e4c5c3b74 # v1.314.0
+        with:
+          bundler-cache: true
+
+      - name: Build documentation
+        run: bundle exec rake rdoc
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v5.0.0
+
+  deploy:
+    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@v5.0.0

.gitignore

@@ -1,6 +1,7 @@
 /.bundle/
 /.yardoc
 /_yardoc/
+/_site/
 /coverage/
 /doc/
 /pkg/

.rdoc_options

@@ -0,0 +1,10 @@
+op_dir: _site
+title: Rubydex
+main_page: README.md
+
+footer_content:
+  DOCUMENTATION:
+    Home: index.html
+  RESOURCES:
+    GitHub Repository: https://github.com/Shopify/rubydex
+    Issue Tracker: https://github.com/Shopify/rubydex/issues

Gemfile

@@ -8,6 +8,7 @@ gemspec
 gem "rake", "~> 13.3"
 gem "rake-compiler"
 gem "minitest"
+gem "rdoc"
 gem "rubocop"
 gem "rubocop-shopify"
 gem "extconf_compile_commands_json"

Gemfile.lock

@@ -7,7 +7,6 @@ GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.3)
-    date (3.5.1)
     drb (2.2.3)
     erb (6.0.4)
     extconf_compile_commands_json (0.0.7)
@@ -40,9 +39,6 @@ GEM
       prettyprint
     prettyprint (0.2.0)
     prism (1.9.0)
-    psych (5.3.1)
-      date
-      stringio
     racc (1.8.1)
     rainbow (3.1.1)
     rake (13.3.1)
@@ -52,9 +48,10 @@ GEM
       logger
       prism (>= 1.6.0)
       tsort
-    rdoc (7.2.0)
+    rdoc (8.0.0)
       erb
-      psych (>= 4.0.0)
+      prism (>= 1.6.0)
+      rbs (>= 4.0.0)
       tsort
     regexp_parser (2.12.0)
     reline (0.6.3)
@@ -78,7 +75,6 @@ GEM
     ruby-progressbar (1.13.0)
     ruby_memcheck (3.0.1)
       nokogiri
-    stringio (3.2.0)
     tsort (0.2.0)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
@@ -96,6 +92,7 @@ DEPENDENCIES
   rake (~> 13.3)
   rake-compiler
   rbs
+  rdoc
   rubocop
   rubocop-shopify
   ruby_memcheck

Rakefile

@@ -4,6 +4,7 @@ require "bundler/gem_tasks"
 require "rubocop/rake_task"
 require "rake/extensiontask"
 require "rake/testtask"
+require "rdoc/task"
 
 GEMSPEC = Gem::Specification.load("rubydex.gemspec")
 
@@ -28,6 +29,10 @@ end
 
 RuboCop::RakeTask.new
 
+RDoc::Task.new do |doc|
+  doc.rdoc_dir = "_site"
+end
+
 task :lint do
   puts "******** Linting ********\n"
   Rake::Task["rubocop"].invoke

ext/rubydex/declaration.c

@@ -5,6 +5,11 @@
 #include "rustbindings.h"
 #include "utils.h"
 
+/*
+ * RDoc parser workaround for https://github.com/ruby/rdoc/issues/1744:
+ * mRubydex = rb_define_module("Rubydex")
+ */
+
 VALUE cDeclaration;
 VALUE cNamespace;
 VALUE cClass;
@@ -46,7 +51,12 @@ VALUE rdxi_declaration_class_for_kind(CDeclarationKind kind) {
     }
 }
 
-// Declaration#name -> String
+/*
+ * call-seq:
+ *   name -> String?
+ *
+ * Returns the fully qualified declaration name.
+ */
 static VALUE rdxr_declaration_name(VALUE self) {
     HandleData *data;
     TypedData_Get_Struct(self, HandleData, &handle_type, data);
@@ -65,7 +75,12 @@ static VALUE rdxr_declaration_name(VALUE self) {
     return str;
 }
 
-// Declaration#unqualified_name -> String
+/*
+ * call-seq:
+ *   unqualified_name -> String?
+ *
+ * Returns the declaration name without namespace qualification.
+ */
 static VALUE rdxr_declaration_unqualified_name(VALUE self) {
     HandleData *data;
     TypedData_Get_Struct(self, HandleData, &handle_type, data);
@@ -126,8 +141,12 @@ static VALUE declaration_definitions_size(VALUE self, VALUE _args, VALUE _eobj)
     return SIZET2NUM(len);
 }
 
-// Declaration#definitions: () -> Enumerator[Definition]
-// Returns an enumerator that yields all definitions for this declaration lazily
+/*
+ * call-seq:
+ *   definitions -> Enumerator[Rubydex::Definition]
+ *
+ * Returns an enumerator that yields all definitions for this declaration lazily.
+ */
 static VALUE rdxr_declaration_definitions(VALUE self) {
     if (!rb_block_given_p()) {
         return rb_enumeratorize_with_size(self, rb_str_new2("definitions"), 0, NULL, declaration_definitions_size);
@@ -146,8 +165,12 @@ static VALUE rdxr_declaration_definitions(VALUE self) {
     return self;
 }
 
-// Declaration#member: (String member) -> Declaration
-// Returns a declaration handle for the given member
+/*
+ * call-seq:
+ *   member(name) -> Rubydex::Declaration?
+ *
+ * Returns a declaration handle for the named member, or nil if no member exists.
+ */
 static VALUE rdxr_declaration_member(VALUE self, VALUE name) {
     HandleData *data;
     TypedData_Get_Struct(self, HandleData, &handle_type, data);
@@ -171,8 +194,12 @@ static VALUE rdxr_declaration_member(VALUE self, VALUE name) {
     return rb_class_new_instance(2, argv, decl_class);
 }
 
-// Namespace#find_member: (String member, only_inherited: false) -> Declaration?
-// Searches for a member in the ancestor chain of the declaration
+/*
+ * call-seq:
+ *   find_member(name, only_inherited: false) -> Rubydex::Declaration?
+ *
+ * Searches for a member in the declaration's ancestor chain.
+ */
 static VALUE rdxr_declaration_find_member(int argc, VALUE *argv, VALUE self) {
     VALUE member, opts;
     rb_scan_args(argc, argv, "1:", &member, &opts);
@@ -207,7 +234,12 @@ static VALUE rdxr_declaration_find_member(int argc, VALUE *argv, VALUE self) {
     return rb_class_new_instance(2, result_argv, decl_class);
 }
 
-// Declaration#singleton_class -> SingletonClass
+/*
+ * call-seq:
+ *   singleton_class -> Rubydex::SingletonClass?
+ *
+ * Returns the singleton class declaration, or nil if none exists.
+ */
 static VALUE rdxr_declaration_singleton_class(VALUE self) {
     HandleData *data;
     TypedData_Get_Struct(self, HandleData, &handle_type, data);
@@ -227,7 +259,12 @@ static VALUE rdxr_declaration_singleton_class(VALUE self) {
     return rb_class_new_instance(2, argv, decl_class);
 }
 
-// Declaration#owner -> Declaration
+/*
+ * call-seq:
+ *   owner -> Rubydex::Declaration
+ *
+ * Returns the owner declaration.
+ */
 static VALUE rdxr_declaration_owner(VALUE self) {
     HandleData *data;
     TypedData_Get_Struct(self, HandleData, &handle_type, data);
@@ -247,7 +284,12 @@ static VALUE rdxr_declaration_owner(VALUE self) {
     return rb_class_new_instance(2, argv, decl_class);
 }
 
-// Declaration#ancestors: () -> Enumerator[Declaration]
+/*
+ * call-seq:
+ *   ancestors -> Enumerator[Rubydex::Namespace]
+ *
+ * Returns an enumerator that yields ancestor namespaces.
+ */
 static VALUE rdxr_declaration_ancestors(VALUE self) {
     if (!rb_block_given_p()) {
         return rb_enumeratorize(self, rb_str_new2("ancestors"), 0, NULL);
@@ -270,7 +312,12 @@ static VALUE rdxr_declaration_ancestors(VALUE self) {
     return self;
 }
 
-// Declaration#descendants: () -> Enumerator[Declaration]
+/*
+ * call-seq:
+ *   descendants -> Enumerator[Rubydex::Namespace]
+ *
+ * Returns an enumerator that yields descendant namespaces.
+ */
 static VALUE rdxr_declaration_descendants(VALUE self) {
     if (!rb_block_given_p()) {
         return rb_enumeratorize(self, rb_str_new2("descendants"), 0, NULL);
@@ -293,7 +340,12 @@ static VALUE rdxr_declaration_descendants(VALUE self) {
     return self;
 }
 
-// Namespace#members: () -> Enumerator[Declaration]
+/*
+ * call-seq:
+ *   members -> Enumerator[Rubydex::Declaration]
+ *
+ * Returns an enumerator that yields member declarations.
+ */
 static VALUE rdxr_declaration_members(VALUE self) {
     if (!rb_block_given_p()) {
         return rb_enumeratorize(self, rb_str_new2("members"), 0, NULL);
@@ -334,8 +386,12 @@ static VALUE constant_declaration_references_size(VALUE self, VALUE _args, VALUE
     return SIZET2NUM(len);
 }
 
-// Namespace#references, Constant#references, ConstantAlias#references
-// Returns an enumerator that yields constant references to this declaration
+/*
+ * call-seq:
+ *   references -> Enumerator[Rubydex::ConstantReference]
+ *
+ * Returns an enumerator that yields constant references to this declaration.
+ */
 static VALUE rdxr_constant_declaration_references(VALUE self) {
     if (!rb_block_given_p()) {
         return rb_enumeratorize_with_size(self, rb_str_new2("references"), 0, NULL,
@@ -377,8 +433,12 @@ static VALUE method_declaration_references_size(VALUE self, VALUE _args, VALUE _
     return SIZET2NUM(len);
 }
 
-// Method#references
-// Returns an enumerator that yields method references to this declaration
+/*
+ * call-seq:
+ *   references -> Enumerator[Rubydex::MethodReference]
+ *
+ * Returns an enumerator that yields method references to this declaration.
+ */
 static VALUE rdxr_method_declaration_references(VALUE self) {
     if (!rb_block_given_p()) {
         return rb_enumeratorize_with_size(self, rb_str_new2("references"), 0, NULL,
@@ -402,7 +462,12 @@ static VALUE rdxr_method_declaration_references(VALUE self) {
     return self;
 }
 
-// Placeholder for variable declarations that don't yet support references
+/*
+ * call-seq:
+ *   references -> Array[untyped]
+ *
+ * Returns an empty array because variable declarations do not yet support reference lookup.
+ */
 static VALUE rdxr_variable_declaration_references(VALUE self) {
     return rb_ary_new();
 }
@@ -420,7 +485,12 @@ static VALUE rdxi_visibility_to_symbol(CVisibility visibility) {
     }
 }
 
-// Declaration#visibility -> Symbol
+/*
+ * call-seq:
+ *   visibility -> Symbol
+ *
+ * Returns the declaration visibility.
+ */
 static VALUE rdxr_declaration_visibility(VALUE self) {
     HandleData *data;
     TypedData_Get_Struct(self, HandleData, &handle_type, data);
@@ -439,9 +509,13 @@ static VALUE rdxr_declaration_visibility(VALUE self) {
     return symbol;
 }
 
-// ConstantAlias#target -> Declaration?
-// Returns the first resolved target declaration for this constant alias, or nil if none of its definitions resolved to
-// a target
+/*
+ * call-seq:
+ *   target -> Rubydex::Declaration?
+ *
+ * Returns the first resolved target declaration for this constant alias, or nil if none of its definitions resolved to
+ * a target.
+ */
 static VALUE rdxr_constant_alias_target(VALUE self) {
     HandleData *data;
     TypedData_Get_Struct(self, HandleData, &handle_type, data);