[SPARK-16555] Work around Jekyll error-handling bug which led to silent failures

If a custom Jekyll template tag throws Ruby's equivalent of a "file not found" exception, then Jekyll will stop the doc building process but will exit with a successful status, causing our doc publishing jobs to silently fail.

This is caused by https://github.com/jekyll/jekyll/issues/5104, a case of bad error-handling logic in Jekyll. This patch works around this by updating our `include_example.rb` plugin to catch the exception and exit rather than allowing it to bubble up and be ignored by Jekyll.

I tested this manually with

```
rm ./examples/src/main/scala/org/apache/spark/examples/sql/SparkSQLExample.scala
cd docs
SKIP_API=1 jekyll build
echo $?
```

Author: Josh Rosen <joshrosen@databricks.com>

Closes #14209 from JoshRosen/fix-doc-building.

1 files changed, 9 insertions, 1 deletions

diff --git a/docs/_plugins/include_example.rb b/docs/_plugins/include_example.rb
index 306888801d..6ea1d438f5 100644
--- a/docs/_plugins/include_example.rb
+++ b/docs/_plugins/include_example.rb
@@ -45,7 +45,15 @@ module Jekyll
       @file = File.join(@code_dir, snippet_file)
       @lang = snippet_file.split('.').last
 
-      code = File.open(@file).read.encode("UTF-8")
+      begin
+        code = File.open(@file).read.encode("UTF-8")
+      rescue => e
+        # We need to explicitly exit on execptions here because Jekyll will silently swallow
+        # them, leading to silent build failures (see https://github.com/jekyll/jekyll/issues/5104)
+        puts(e)
+        puts(e.backtrace)
+        exit 1
+      end
       code = select_lines(code)
 
       rendered_code = Pygments.highlight(code, :lexer => @lang)