Inject markdown inside scaladoc static site

vitlinda commented 2 years ago

Compiler version

3.1.3-RC4

Minimized example

According to the Liquid documentation, I would be able to inject the content of example.md into another markdown file.

{% render example.md %}

Output

The sbt task doc fails with the following exception:

click to see Stack trace

```scala [error] java.lang.RuntimeException: java.lang.reflect.InvocationTargetException [error] at xsbt.DottydocRunner.run(DottydocRunner.java:65) [error] at xsbt.ScaladocInterface.run(ScaladocInterface.java:11) [error] at jdk.internal.reflect.GeneratedMethodAccessor5.invoke(Unknown Source) [error] at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) [error] at java.base/java.lang.reflect.Method.invoke(Method.java:567) [error] at sbt.internal.inc.AnalyzingCompiler.invoke(AnalyzingCompiler.scala:329) [error] at sbt.internal.inc.AnalyzingCompiler.doc(AnalyzingCompiler.scala:175) [error] at sbt.internal.inc.AnalyzingCompiler.doc(AnalyzingCompiler.scala:133) [error] at sbt.Doc$.$anonfun$scaladoc$1(Doc.scala:52) [error] at sbt.Doc$.$anonfun$scaladoc$1$adapted(Doc.scala:40) [error] at sbt.RawCompileLike$.$anonfun$prepare$1(RawCompileLike.scala:79) [error] at sbt.RawCompileLike$.$anonfun$prepare$1$adapted(RawCompileLike.scala:72) [error] at sbt.RawCompileLike$.$anonfun$cached$4(RawCompileLike.scala:63) [error] at sbt.RawCompileLike$.$anonfun$cached$4$adapted(RawCompileLike.scala:61) [error] at sbt.util.Tracked$.$anonfun$inputChangedW$1(Tracked.scala:219) [error] at sbt.RawCompileLike$.$anonfun$cached$1(RawCompileLike.scala:68) [error] at sbt.RawCompileLike$.$anonfun$cached$1$adapted(RawCompileLike.scala:52) [error] at sbt.Defaults$.$anonfun$docTaskSettings$4(Defaults.scala:2159) [error] at scala.Function1.$anonfun$compose$1(Function1.scala:49) [error] at sbt.internal.util.$tilde$greater.$anonfun$$u2219$1(TypeFunctions.scala:62) [error] at sbt.std.Transform$$anon$4.work(Transform.scala:68) [error] at sbt.Execute.$anonfun$submit$2(Execute.scala:282) [error] at sbt.internal.util.ErrorHandling$.wideConvert(ErrorHandling.scala:23) [error] at sbt.Execute.work(Execute.scala:291) [error] at sbt.Execute.$anonfun$submit$1(Execute.scala:282) [error] at sbt.ConcurrentRestrictions$$anon$4.$anonfun$submitValid$1(ConcurrentRestrictions.scala:265) [error] at sbt.CompletionService$$anon$2.call(CompletionService.scala:64) [error] at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:264) [error] at java.base/java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:515) [error] at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:264) [error] at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1130) [error] at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:630) [error] at java.base/java.lang.Thread.run(Thread.java:831) [error] Caused by: java.lang.reflect.InvocationTargetException [error] at jdk.internal.reflect.GeneratedMethodAccessor6.invoke(Unknown Source) [error] at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) [error] at java.base/java.lang.reflect.Method.invoke(Method.java:567) [error] at xsbt.DottydocRunner.run(DottydocRunner.java:61) [error] at xsbt.ScaladocInterface.run(ScaladocInterface.java:11) [error] at jdk.internal.reflect.GeneratedMethodAccessor5.invoke(Unknown Source) [error] at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) [error] at java.base/java.lang.reflect.Method.invoke(Method.java:567) [error] at sbt.internal.inc.AnalyzingCompiler.invoke(AnalyzingCompiler.scala:329) [error] at sbt.internal.inc.AnalyzingCompiler.doc(AnalyzingCompiler.scala:175) [error] at sbt.internal.inc.AnalyzingCompiler.doc(AnalyzingCompiler.scala:133) [error] at sbt.Doc$.$anonfun$scaladoc$1(Doc.scala:52) [error] at sbt.Doc$.$anonfun$scaladoc$1$adapted(Doc.scala:40) [error] at sbt.RawCompileLike$.$anonfun$prepare$1(RawCompileLike.scala:79) [error] at sbt.RawCompileLike$.$anonfun$prepare$1$adapted(RawCompileLike.scala:72) [error] at sbt.RawCompileLike$.$anonfun$cached$4(RawCompileLike.scala:63) [error] at sbt.RawCompileLike$.$anonfun$cached$4$adapted(RawCompileLike.scala:61) [error] at sbt.util.Tracked$.$anonfun$inputChangedW$1(Tracked.scala:219) [error] at sbt.RawCompileLike$.$anonfun$cached$1(RawCompileLike.scala:68) [error] at sbt.RawCompileLike$.$anonfun$cached$1$adapted(RawCompileLike.scala:52) [error] at sbt.Defaults$.$anonfun$docTaskSettings$4(Defaults.scala:2159) [error] at scala.Function1.$anonfun$compose$1(Function1.scala:49) [error] at sbt.internal.util.$tilde$greater.$anonfun$$u2219$1(TypeFunctions.scala:62) [error] at sbt.std.Transform$$anon$4.work(Transform.scala:68) [error] at sbt.Execute.$anonfun$submit$2(Execute.scala:282) [error] at sbt.internal.util.ErrorHandling$.wideConvert(ErrorHandling.scala:23) [error] at sbt.Execute.work(Execute.scala:291) [error] at sbt.Execute.$anonfun$submit$1(Execute.scala:282) [error] at sbt.ConcurrentRestrictions$$anon$4.$anonfun$submitValid$1(ConcurrentRestrictions.scala:265) [error] at sbt.CompletionService$$anon$2.call(CompletionService.scala:64) [error] at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:264) [error] at java.base/java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:515) [error] at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:264) [error] at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1130) [error] at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:630) [error] at java.base/java.lang.Thread.run(Thread.java:831) [error] Caused by: java.lang.RuntimeException: The tag 'render' is not registered. [error] at liqp.parser.v4.NodeVisitor.visitOther_tag(NodeVisitor.java:106) [error] at liqp.parser.v4.NodeVisitor.visitOther_tag(NodeVisitor.java:24) [error] at liquid.parser.v4.LiquidParser$Other_tagContext.accept(LiquidParser.java:588) [error] at org.antlr.v4.runtime.tree.AbstractParseTreeVisitor.visitChildren(AbstractParseTreeVisitor.java:46) [error] at liquid.parser.v4.LiquidParserBaseVisitor.visitTag(LiquidParserBaseVisitor.java:62) [error] at liquid.parser.v4.LiquidParser$TagContext.accept(LiquidParser.java:453) [error] at org.antlr.v4.runtime.tree.AbstractParseTreeVisitor.visitChildren(AbstractParseTreeVisitor.java:46) [error] at liquid.parser.v4.LiquidParserBaseVisitor.visitAtom_tag(LiquidParserBaseVisitor.java:34) [error] at liquid.parser.v4.LiquidParser$Atom_tagContext.accept(LiquidParser.java:326) [error] at org.antlr.v4.runtime.tree.AbstractParseTreeVisitor.visit(AbstractParseTreeVisitor.java:18) [error] at liqp.parser.v4.NodeVisitor.visitBlock(NodeVisitor.java:65) [error] at liqp.parser.v4.NodeVisitor.visitParse(NodeVisitor.java:52) [error] at liqp.parser.v4.NodeVisitor.visitParse(NodeVisitor.java:24) [error] at liquid.parser.v4.LiquidParser$ParseContext.accept(LiquidParser.java:172) [error] at org.antlr.v4.runtime.tree.AbstractParseTreeVisitor.visit(AbstractParseTreeVisitor.java:18) [error] at liqp.Template.renderUnguarded(Template.java:489) [error] at liqp.Template.renderUnguarded(Template.java:470) [error] at liqp.Template.render(Template.java:424) [error] at dotty.tools.scaladoc.site.TemplateFile.resolveInner(templates.scala:120) [error] at dotty.tools.scaladoc.site.LoadedTemplate.resolveToHtml(LoadedTemplate.scala:56) [error] at dotty.tools.scaladoc.renderers.ResolvedTemplate.(SiteRenderer.scala:19) [error] at dotty.tools.scaladoc.renderers.ResolvedTemplate$.apply(SiteRenderer.scala:18) [error] at dotty.tools.scaladoc.renderers.SiteRenderer.templateToPage(SiteRenderer.scala:26) [error] at dotty.tools.scaladoc.renderers.SiteRenderer.templateToPage$(SiteRenderer.scala:22) [error] at dotty.tools.scaladoc.renderers.Renderer.templateToPage(Renderer.scala:27) [error] at dotty.tools.scaladoc.renderers.SiteRenderer.templateToPage$$anonfun$1(SiteRenderer.scala:27) [error] at scala.collection.immutable.List.map(List.scala:246) [error] at dotty.tools.scaladoc.renderers.SiteRenderer.templateToPage(SiteRenderer.scala:27) [error] at dotty.tools.scaladoc.renderers.SiteRenderer.templateToPage$(SiteRenderer.scala:22) [error] at dotty.tools.scaladoc.renderers.Renderer.templateToPage(Renderer.scala:27) [error] at dotty.tools.scaladoc.renderers.Renderer.$anonfun$4(Renderer.scala:97) [error] at scala.collection.immutable.List.map(List.scala:246) [error] at dotty.tools.scaladoc.renderers.Renderer.(Renderer.scala:97) [error] at dotty.tools.scaladoc.renderers.HtmlRenderer.(HtmlRenderer.scala:19) [error] at dotty.tools.scaladoc.Scaladoc$.run(Scaladoc.scala:231) [error] at dotty.tools.scaladoc.Scaladoc$.run$$anonfun$1(Scaladoc.scala:72) [error] at scala.runtime.function.JProcedure1.apply(JProcedure1.java:15) [error] at scala.runtime.function.JProcedure1.apply(JProcedure1.java:10) [error] at scala.Option.map(Option.scala:242) [error] at dotty.tools.scaladoc.Scaladoc$.run(Scaladoc.scala:76) [error] at dotty.tools.dottydoc.Main$.process(Main.scala:25) [error] at dotty.tools.dottydoc.Main.process(Main.scala) [error] at jdk.internal.reflect.GeneratedMethodAccessor6.invoke(Unknown Source) [error] at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) [error] at java.base/java.lang.reflect.Method.invoke(Method.java:567) [error] at xsbt.DottydocRunner.run(DottydocRunner.java:61) [error] at xsbt.ScaladocInterface.run(ScaladocInterface.java:11) [error] at jdk.internal.reflect.GeneratedMethodAccessor5.invoke(Unknown Source) [error] at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) [error] at java.base/java.lang.reflect.Method.invoke(Method.java:567) [error] at sbt.internal.inc.AnalyzingCompiler.invoke(AnalyzingCompiler.scala:329) [error] at sbt.internal.inc.AnalyzingCompiler.doc(AnalyzingCompiler.scala:175) [error] at sbt.internal.inc.AnalyzingCompiler.doc(AnalyzingCompiler.scala:133) [error] at sbt.Doc$.$anonfun$scaladoc$1(Doc.scala:52) [error] at sbt.Doc$.$anonfun$scaladoc$1$adapted(Doc.scala:40) [error] at sbt.RawCompileLike$.$anonfun$prepare$1(RawCompileLike.scala:79) [error] at sbt.RawCompileLike$.$anonfun$prepare$1$adapted(RawCompileLike.scala:72) [error] at sbt.RawCompileLike$.$anonfun$cached$4(RawCompileLike.scala:63) [error] at sbt.RawCompileLike$.$anonfun$cached$4$adapted(RawCompileLike.scala:61) [error] at sbt.util.Tracked$.$anonfun$inputChangedW$1(Tracked.scala:219) [error] at sbt.RawCompileLike$.$anonfun$cached$1(RawCompileLike.scala:68) [error] at sbt.RawCompileLike$.$anonfun$cached$1$adapted(RawCompileLike.scala:52) [error] at sbt.Defaults$.$anonfun$docTaskSettings$4(Defaults.scala:2159) [error] at scala.Function1.$anonfun$compose$1(Function1.scala:49) [error] at sbt.internal.util.$tilde$greater.$anonfun$$u2219$1(TypeFunctions.scala:62) [error] at sbt.std.Transform$$anon$4.work(Transform.scala:68) [error] at sbt.Execute.$anonfun$submit$2(Execute.scala:282) [error] at sbt.internal.util.ErrorHandling$.wideConvert(ErrorHandling.scala:23) [error] at sbt.Execute.work(Execute.scala:291) [error] at sbt.Execute.$anonfun$submit$1(Execute.scala:282) [error] at sbt.ConcurrentRestrictions$$anon$4.$anonfun$submitValid$1(ConcurrentRestrictions.scala:265) [error] at sbt.CompletionService$$anon$2.call(CompletionService.scala:64) [error] at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:264) [error] at java.base/java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:515) [error] at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:264) [error] at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1130) [error] at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:630) [error] at java.base/java.lang.Thread.run(Thread.java:831) [error] (Compile / doc) java.lang.reflect.InvocationTargetException ```

Expectation

I would expect to see the content of example.md injected in the other file

ndido98 commented 2 years ago

Working together with @vitlinda, we troubleshooted this issue. By poking around in liqp in horrendous ways (i.e. manually patching the .jar file), we discovered that:

the used liqp version still uses the old include syntax instead of the new render syntax
inclusion errors are silenced, because the default render settings don't have the showExceptionsFromInclude flag enabled, and that leads to all include-related exceptions being silenced; this should be a relatively easy fix by just passing the properly set render settings to the rendering function (after taking a look at Scaladoc's source, I suppose this is the one)
for reasons we still haven't figured out, liqp ignores the site root parameter set in Scaladoc and looks for the files to include in the _includes directory (snippets in Scala 3.1.2, because for some reason it uses the Liquid flavor instead of Jekyll) in the project root

Basically, the situation is this:

<project root>
├── docs (site root)
│   ├── _docs
│   └── _includes (I expected liqp to look here)
└── _includes (instead it looks here)

A quick and dirty fix would be to change the includes directory by setting the liqp@includes_directory key inside the rendering context, but I don't know if there are any better solutions.

ndido98 commented 2 years ago

Any update on this issue?

scala / scala3