Merge branch 'master' into document_is_not_a_comment

Author: st0012

.github/workflows/gh-pages.yml

@@ -22,7 +22,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
       - name: Setup Ruby
-        uses: ruby/setup-ruby@bfefad842bb982ff05b233bcbc1571d97a87e69f # v1.206.0
+        uses: ruby/setup-ruby@1287d2b408066abada82d5ad1c63652e758428d9 # v1.214.0
         with:
           ruby-version: '3.2'
           bundler-cache: true

.github/workflows/push_gem.yml

@@ -23,14 +23,14 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
+        uses: step-security/harden-runner@cb605e52c26070c328afc4562f0b4ada7618a84e # v2.10.4
         with:
           egress-policy: audit
 
       - uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4
 
       - name: Set up Ruby
-        uses: ruby/setup-ruby@bfefad842bb982ff05b233bcbc1571d97a87e69f # v1.206.0
+        uses: ruby/setup-ruby@1287d2b408066abada82d5ad1c63652e758428d9 # v1.214.0
         with:
           bundler-cache: true
           ruby-version: ruby

.github/workflows/ruby-core.yml

@@ -15,14 +15,14 @@ permissions: # added using https://github.com/step-security/secure-workflows
 
 jobs:
   ruby_core:
-    name: RDoc under a ruby-core setup
+    name: Generate ruby/ruby documentation with the current RDoc commit
     runs-on: ubuntu-20.04
     strategy:
       fail-fast: false
     timeout-minutes: 30
     steps:
       - name: Set up latest ruby head
-        uses: ruby/setup-ruby@bfefad842bb982ff05b233bcbc1571d97a87e69f # v1.206.0
+        uses: ruby/setup-ruby@1287d2b408066abada82d5ad1c63652e758428d9 # v1.214.0
         with:
           ruby-version: head
           bundler: none
@@ -45,15 +45,26 @@ jobs:
         run: |
           autoconf
           ./configure -C --disable-install-doc
-          make -j2
         working-directory: ruby/ruby
       - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v3.1.0
         with:
           path: ruby/rdoc
-      - name: Sync tools
+      - name: Build RDoc locally
         run: |
-          ruby tool/sync_default_gems.rb rdoc
+          bundle install
+          bundle exec rake build:local_ruby
+        working-directory: ruby/rdoc
+      - name: Generate Documentation with RDoc
+        run: make html
         working-directory: ruby/ruby
-      - name: Test RDoc
-        run: make -j2 -s test-all TESTS="rdoc --no-retry"
+      # We need to clear the generated documentation to generate them again
+      # with the Prism parser.
+      - name: Clear Generated Documentation
+        run: rm -r .ext/html
         working-directory: ruby/ruby
+      - name: Generate Documentation with RDoc (Prism parser)
+        run: make html
+        working-directory: ruby/ruby
+        env:
+          RDOC_USE_PRISM_PARSER: true
+

.github/workflows/test.yml

@@ -11,6 +11,7 @@ jobs:
     with:
       # 2.7 breaks `test_parse_statements_nodoc_identifier_alias_method`
       min_version: 3.0
+      versions: '["mswin"]'
       engine: cruby-truffleruby
 
   test:
@@ -25,9 +26,11 @@ jobs:
             ruby: truffleruby
           - os: windows-latest
             ruby: truffleruby-head
-          # Remove it once https://github.com/ruby/setup-ruby/issues/680 is fixed
-          - os: windows-latest
-            ruby: 3.4
+          - os: macos-latest
+            ruby: mswin
+          - os: ubuntu-latest
+            ruby: mswin
+
     runs-on: ${{ matrix.os }}
     steps:
     - uses: actions/checkout@v4 # v3.3.0

.rdoc_options

@@ -1,9 +1,6 @@
-exclude:
-  - lib/rdoc/rd/block_parser.ry
-  - lib/rdoc/rd/inline_parser.ry
-  - lib/rdoc/markdown.kpeg
-  - lib/rdoc/markdown/literals.kpeg
 op_dir: _site # for GitHub Pages and should match the config of RDoc task in Rakefile
 title: rdoc Documentation
 main_page: README.rdoc
 warn_missing_rdoc_ref: true
+autolink_excluded_words:
+- RDoc

Rakefile

@@ -99,6 +99,19 @@ task :clean do
   end
 end
 
+desc "Build #{Bundler::GemHelper.gemspec.full_name} and move it to local ruby/ruby project's bundled gems folder"
+namespace :build do
+  task local_ruby: :build do
+    target = File.join("..", "ruby", "gems")
+
+    unless File.directory?(target)
+      abort("Expected Ruby to be cloned under the same parent directory as RDoc to use this task")
+    end
+
+    mv("#{path}.gem", target)
+  end
+end
+
 begin
   require 'rubocop/rake_task'
 rescue LoadError

doc/rdoc/markup_reference.rb

@@ -996,8 +996,7 @@
 #   and entire <tt>rdoc-ref:</tt> square-bracketed clause is removed
 #   from the resulting text.
 #
-#   - <tt>Nosuch[rdoc-ref:RDoc::Nosuch]</tt> generates
-#     Nosuch[rdoc-ref:RDoc::Nosuch].
+#   - <tt>Nosuch[rdoc-ref:RDoc::Nosuch]</tt> generates Nosuch.
 #
 #
 # [<tt>rdoc-label</tt> Scheme]

lib/rdoc/generator/darkfish.rb

@@ -316,11 +316,14 @@ def generate_index
     asset_rel_prefix = rel_prefix + @asset_rel_path
 
     @title = @options.title
+    @main_page = @files.find { |f| f.full_name == @options.main_page }
 
     render_template template_file, out_file do |io|
       here = binding
       # suppress 1.9.3 warning
       here.local_variable_set(:asset_rel_prefix, asset_rel_prefix)
+      # some partials rely on the presence of current variable to render
+      here.local_variable_set(:current, @main_page) if @main_page
       here
     end
   rescue => e

lib/rdoc/generator/template/darkfish/index.rhtml

@@ -7,17 +7,17 @@
     <%= render '_sidebar_search.rhtml' %>
   </div>
 
+  <%= render '_sidebar_table_of_contents.rhtml' if defined?(current) %>
   <%= render '_sidebar_pages.rhtml' %>
   <%= render '_sidebar_classes.rhtml' %>
 
   <%= render '_footer.rhtml' %>
 </nav>
 
 <main role="main">
-<%- if @options.main_page and
-      main_page = @files.find { |f| f.full_name == @options.main_page } then %>
-<%= main_page.description %>
+<%- if @main_page %>
+  <%= @main_page.description %>
 <%- else -%>
-<p>This is the API documentation for <%= h @title %>.
+  <p>This is the API documentation for <%= h @title %>.
 <%- end -%>
 </main>

lib/rdoc/markdown/.document

@@ -0,0 +1 @@
+*.rb