docs: use jekyll-rtd-theme from a ruby gem

The upstream repo (and the release downloads)
github.com/rundocs/jekyll-rtd-theme has been deleted. This broke our
docs generation as the remote theme configuration depended on
downloading the release artefact.

This patch changes the docs building to use a Ruby gem instead of the
remote theme setting. To complicate matters, the gem has an seemingly
incorrect (too strict) version dependency. To mitigate this, we now
install bundler-override plugin to ignore this particular dependency.

The netlify conf is a hack, but I wasn't able to figure out a way how to
install the bundler-override plugin without doing all ruby
initialization in the build command.

Author: marquiz

Makefile

@@ -246,11 +246,11 @@ poll-images:
 
 site-build:
 	@mkdir -p docs/vendor/bundle
-	$(SITE_BUILD_CMD) sh -c "bundle install && jekyll build $(JEKYLL_OPTS)"
+	$(SITE_BUILD_CMD) sh -c "bundle plugin install bundler-override && bundle install && jekyll build $(JEKYLL_OPTS)"
 
 site-serve:
 	@mkdir -p docs/vendor/bundle
-	$(SITE_BUILD_CMD) sh -c "bundle install && jekyll serve $(JEKYLL_OPTS) -H 127.0.0.1"
+	$(SITE_BUILD_CMD) sh -c "bundle plugin install bundler-override && bundle install && jekyll serve $(JEKYLL_OPTS) -H 127.0.0.1"
 
 benchmark:
 	go test -bench=./pkg/nfd-master -run=^# ./pkg/nfd-master

docs/Gemfile

@@ -1,5 +1,11 @@
 source "https://rubygems.org"
 
+# Use override plugin to drop incorrect dependency of jekyll-rtd-them on github-pages (~> 209)
+# The original dep would allow github-pages v209.x but not v210 or later.
+plugin 'bundler-override'
+require File.join(Bundler::Plugin.index.load_paths("bundler-override")[0], "bundler-override") rescue nil
+override 'jekyll-rtd-theme', :drop => "github-pages"
+
 # Hello! This is where you manage which Jekyll version is used to run.
 # When you want to use a different version, change it below, save the
 # file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
@@ -29,3 +35,5 @@ gem "wdm", "~> 0.1.1", :install_if => Gem.win_platform?
 #gem "kramdown-parser-gfm"
 
 gem "webrick", "~> 1.8"
+
+gem 'jekyll-rtd-theme', '~> 2.0', '>= 2.0.10'

docs/Gemfile.lock

@@ -152,6 +152,7 @@ GEM
       jekyll (>= 3.5, < 5.0)
       jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0)
       rubyzip (>= 1.3.0, < 3.0)
+    jekyll-rtd-theme (2.0.10)
     jekyll-sass-converter (1.5.2)
       sass (~> 3.4)
     jekyll-seo-tag (2.8.0)
@@ -274,10 +275,11 @@ PLATFORMS
 DEPENDENCIES
   github-pages (~> 228)
   jekyll (~> 3.9.0)
+  jekyll-rtd-theme (~> 2.0, >= 2.0.10)
   tzinfo (~> 2.0)
   tzinfo-data
   wdm (~> 0.1.1)
   webrick (~> 1.8)
 
 BUNDLED WITH
-   2.0.2
+   2.3.27

docs/_config.yml

@@ -26,9 +26,7 @@ markdown: kramdown
 kramdown:
   toc_levels: 1..3
 
-remote_theme: rundocs/[email protected]
-plugins:
-  - jekyll-remote-theme
+theme: jekyll-rtd-theme
 
 # Exclude from processing.
 # The following items will not be processed, by default. Create a custom list

netlify.toml

@@ -1,4 +1,4 @@
 # Netlify settings
 [build]
-    command = "cd docs/ && bundle install && jekyll build"
-    publish = "docs/_site/"
+    command = "cd docs/ && source /opt/buildhome/.rvm/scripts/rvm && rvm install ruby-3.1.6 && bundle plugin install bundler-override && bundle install && jekyll build"
+    publish = "docs/_site/"