Bug #21201


Documentation build fails on Debian 12 after Ruby 3 migration

Added by Brett Smith 8 months ago. Updated 2 months ago.

Assigned To:
Story points:
Release relationship:


I am running on Debian 12 and have run arvados-server install -type test as of main at 7bc4217495b405c98ea4cad8178b8136383486cf. When I try to build the documentation, I get the following error:

Rendering .site/sdk/R/index.html
rake aborted!
Kramdown::Error: Unknown parser: codeblock
/home/brett/.local/lib/rubygems/gems/kramdown-1.17.0/lib/kramdown/parser/kramdown.rb:126:in `block in configure_parser'
/home/brett/.local/lib/rubygems/gems/kramdown-1.17.0/lib/kramdown/parser/kramdown.rb:122:in `each'
/home/brett/.local/lib/rubygems/gems/kramdown-1.17.0/lib/kramdown/parser/kramdown.rb:122:in `configure_parser'
/home/brett/.local/lib/rubygems/gems/kramdown-1.17.0/lib/kramdown/parser/kramdown.rb:88:in `parse'
/home/brett/.local/lib/rubygems/gems/kramdown-1.17.0/lib/kramdown/parser/base.rb:69:in `parse'
/home/brett/.local/lib/rubygems/gems/kramdown-1.17.0/lib/kramdown/document.rb:104:in `initialize'
/home/brett/.local/lib/rubygems/gems/zenweb-3.10.6/lib/zenweb/plugins/markdown.rb:42:in `new'
/home/brett/.local/lib/rubygems/gems/zenweb-3.10.6/lib/zenweb/plugins/markdown.rb:42:in `markdown'
/home/brett/.local/lib/rubygems/gems/zenweb-3.10.6/lib/zenweb/plugins/markdown.rb:18:in `render_md'
/home/brett/.local/lib/rubygems/gems/zenweb-3.10.6/lib/zenweb/page.rb:387:in `block in subrender'
/home/brett/.local/lib/rubygems/gems/zenweb-3.10.6/lib/zenweb/page.rb:386:in `each'
/home/brett/.local/lib/rubygems/gems/zenweb-3.10.6/lib/zenweb/page.rb:386:in `inject'
/home/brett/.local/lib/rubygems/gems/zenweb-3.10.6/lib/zenweb/page.rb:386:in `subrender'
/home/brett/.local/lib/rubygems/gems/zenweb-3.10.6/lib/zenweb/page.rb:360:in `render'
/home/brett/.local/lib/rubygems/gems/zenweb-3.10.6/lib/zenweb/page.rb:271:in `generate'
/home/brett/.local/lib/rubygems/gems/zenweb-3.10.6/lib/zenweb/page.rb:482:in `block in wire'
/home/brett/.local/lib/rubygems/gems/zenweb-3.10.6/lib/zenweb/site.rb:103:in `generate'
/home/brett/.local/lib/rubygems/gems/zenweb-3.10.6/lib/zenweb/tasks.rake:21:in `block in <top (required)>'
/home/brett/.gem/ruby/3.2.0/gems/rake-13.0.6/exe/rake:27:in `<top (required)>'
/home/brett/.local/lib/rubygems/gems/bundler-2.1.4/lib/bundler/cli/exec.rb:63:in `load'
/home/brett/.local/lib/rubygems/gems/bundler-2.1.4/lib/bundler/cli/exec.rb:63:in `kernel_load'
/home/brett/.local/lib/rubygems/gems/bundler-2.1.4/lib/bundler/cli/exec.rb:28:in `run'
/home/brett/.local/lib/rubygems/gems/bundler-2.1.4/lib/bundler/cli.rb:476:in `exec'
/home/brett/.local/lib/rubygems/gems/bundler-2.1.4/lib/bundler/vendor/thor/lib/thor/command.rb:27:in `run'
/home/brett/.local/lib/rubygems/gems/bundler-2.1.4/lib/bundler/vendor/thor/lib/thor/invocation.rb:127:in `invoke_command'
/home/brett/.local/lib/rubygems/gems/bundler-2.1.4/lib/bundler/vendor/thor/lib/thor.rb:399:in `dispatch'
/home/brett/.local/lib/rubygems/gems/bundler-2.1.4/lib/bundler/cli.rb:30:in `dispatch'
/home/brett/.local/lib/rubygems/gems/bundler-2.1.4/lib/bundler/vendor/thor/lib/thor/base.rb:476:in `start'
/home/brett/.local/lib/rubygems/gems/bundler-2.1.4/lib/bundler/cli.rb:24:in `start'
/home/brett/.local/lib/rubygems/gems/bundler-2.1.4/exe/bundle:46:in `block in <top (required)>'
/home/brett/.local/lib/rubygems/gems/bundler-2.1.4/lib/bundler/friendly_errors.rb:123:in `with_friendly_errors'
/home/brett/.local/lib/rubygems/gems/bundler-2.1.4/exe/bundle:34:in `<top (required)>'
/opt/arvados/bin/bundle:25:in `load'
/opt/arvados/bin/bundle:25:in `<main>'
Tasks: TOP => site => .site/index.html => .site/sdk/index.html => .site/sdk/R/index.html
(See full trace by running task with --trace)

Since this error is in the R SDK docs, I tried with NO_SDK=1, but that just moves the problem:

Rendering .site/user/cwl/arvados-vscode-training.html          
rake aborted!                                                                                                                                                                
Kramdown::Error: Unknown parser: codeblock                  
[same stack trace omitted]
Tasks: TOP => site => .site/index.html => .site/user/index.html => .site/user/cwl/arvados-vscode-training.html
(See full trace by running task with --trace)

For what it's worth, I also get these warnings at the start of the run:

Calling `DidYouMean::SPELL_CHECKERS.merge!(error_name => spell_checker)' has been deprecated. Please call `DidYouMean.correct_error(error_name, spell_checker)' instead.     
zenweb-fix-body.rb:4: warning: already initialized constant ZenwebTextile::VERSION                                                                                           
zenweb-textile.rb:8: warning: previous definition of VERSION was here                                                                                                        


Gemfile.lock (780 Bytes) Gemfile.lock for Ruby 3.2.2 on 2023-11-19 Brett Smith, 11/20/2023 03:24 AM

Subtasks 1 (0 open1 closed)

Task #21203: Review 21201-doc-bundle-updateResolvedBrett Smith11/20/2023Actions
Actions #1

Updated by Brett Smith 8 months ago

  • Story points set to 0.5
  • Target version changed from Future to Development 2023-11-29 sprint
  • Assigned To set to Brett Smith
  • Status changed from New to In Progress
  • File Gemfile.lock Gemfile.lock added

For whatever it's worth, I cleared all my gems and Bundle cache and re-set everything up, and it still failed the same way. Which is what I expected, but good to confirm.

It works if I bundle update. I've attached the Gemfile.lock I got from that, just for posterity. The Zenweb changelog does have a couple of bugfix releases related to kramdown between 3.10.6 (the current version used by main) and 3.11.0 (the version I got). It seems plausible that getting newer kramdown helps it work with newer Ruby or something.

If we confirm this still works with Ruby 2.7 I can probably just merge it to main?

Actions #2

Updated by Brett Smith 8 months ago

Brett Smith wrote in #note-1:

If we confirm this still works with Ruby 2.7 I can probably just merge it to main?

21201-doc-bundle-update @ 8f8c63166dcfbd1cd02d426cc6d83a93bfb6c0fa

Main test run: developer-run-tests: #3914

doc-and-sdk-R rerun: developer-run-tests-doc-and-sdk-R: #2079

You are going to look at this and think "The doc tests needed a rerun? That's fishy." I agree! But if you look at the console output of the failed run, you'll see the doc tests ran fine, instead the sdk/R tests failed when trying to kill a process, which smells extremely racey. There's no way this branch caused that failure.

  • All agreed upon points are implemented / addressed.
    • Fixes the reported crash
  • Anything not implemented (discovered or discussed during work) has a follow-up story.
    • N/A
  • Code is tested and passing, both automated and manual, what manual testing was done is described
    • I ran on my Ruby 3.2 install and spot-checked the rendered documentation and it looks normal. The runs above show that it continues to work on Ruby 2.7. There's a small chance that the documentation build "succeeds" but doesn't actually render right on Ruby 2.7. If that's the case, worst case scenario we just revert this branch, it's not that big of a deal.
  • Documentation has been updated.
    • N/A, pure dependency upgrade
  • Behaves appropriately at the intended scale (describe intended scale).
    • No scale changes
  • Considered backwards and forwards compatibility issues between client and server.
    • N/A, only affects documentation build
  • Follows our coding standards and GUI style guidelines.
    • N/A, automated change
Actions #3

Updated by Tom Clegg 8 months ago

21201-doc-bundle-update LGTM, thanks

Actions #4

Updated by Brett Smith 8 months ago

  • Status changed from In Progress to Resolved
Actions #5

Updated by Peter Amstutz 2 months ago

  • Release set to 70

Also available in: Atom PDF