How to generate docs via a Github workflow? #950

kaihendry · 2025-02-13T13:06:48Z

kaihendry
Feb 13, 2025

My goal is to publish docs from /~https://github.com/kaihendry/pkl-redis/blob/main/control.pkl upon github pages.

My expectation was for a workflow like pkl-community/setup-pkl@v0 for the docs generation.

My only search result for "pkldoc" was /~https://github.com/kdeps/schema/blob/main/.github/workflows/release.yaml which seems non-trivial. Is there a better example to help me please reach my goal?

StefMa · 2025-02-13T15:10:45Z

StefMa
Feb 13, 2025

You just need to do one step after the other I guess 😅
There is actually no "out-of-the-box" solution doing this right know.
But since you mention pkl-community/setup-pkl, its actually a great idea to create something like this 🙃

Anyways, I guess the release.yml you linked (this time as a hash), is actually everything you need.
Since you don't use gradle, you can use the cli to generate the docs.
I posted my workthrough (without big success yet honestly) here:
StefMa/pkl-gha#27 (comment)

You kinda can replace this part with the create docs step in the linked release.yml file and "that should be it".

Hope this helps so far.
Let me know if you were successful or stuck anywere.

3 replies

kaihendry Feb 14, 2025
Author

👋 I'm stuck at java.lang.NoSuchMethodError: 'void sun.misc.Unsafe.ensureClassInitialized(java.lang.Class)'

❯ java -version
java version "23.0.2" 2025-01-21
Java(TM) SE Runtime Environment Oracle GraalVM 23.0.2+7.1 (build 23.0.2+7-jvmci-b01)
Java HotSpot(TM) 64-Bit Server VM Oracle GraalVM 23.0.2+7.1 (build 23.0.2+7-jvmci-b01, mixed mode, sharing)

pkl-gha on  main (59802f6)
❯ jbang run --main org.pkl.doc.Main "org.pkl-lang:pkl-doc:0.26.3" GitHubAction.pkl doc-package-info.pkl -o .out
Exception in thread "main" java.lang.NoSuchMethodError: 'void sun.misc.Unsafe.ensureClassInitialized(java.lang.Class)'
	at com.oracle.truffle.api.library.LibraryFactory.ensureLibraryInitialized(LibraryFactory.java:384)
	at com.oracle.truffle.api.library.LibraryFactory.getUncached(LibraryFactory.java:364)
	at com.oracle.truffle.api.library.LibraryFactory.<init>(LibraryFactory.java:210)
	at com.oracle.truffle.api.interop.InteropLibraryGen.<init>(InteropLibraryGen.java:178)
	at com.oracle.truffle.api.interop.InteropLibraryGen.<clinit>(InteropLibraryGen.java:169)
	at java.base/java.lang.Class.forName0(Native Method)
	at java.base/java.lang.Class.forName(Class.java:578)
	at java.base/java.lang.Class.forName(Class.java:557)
	at com.oracle.truffle.api.library.LibraryFactory.loadGeneratedClass(LibraryFactory.java:791)
	at com.oracle.truffle.api.library.LibraryFactory.resolveImpl(LibraryFactory.java:740)
	at com.oracle.truffle.api.library.LibraryFactory.resolve(LibraryFactory.java:733)
	at com.oracle.truffle.api.interop.InteropLibrary.<clinit>(InteropLibrary.java:2941)
	at com.oracle.truffle.polyglot.PolyglotValueDispatch.<clinit>(PolyglotValueDispatch.java:170)
	at com.oracle.truffle.polyglot.PolyglotImpl.initialize(PolyglotImpl.java:166)
	at org.graalvm.polyglot.impl.AbstractPolyglotImpl.setConstructors(AbstractPolyglotImpl.java:288)
	at org.graalvm.polyglot.Engine$1.loadAndValidateProviders(Engine.java:1107)
	at org.graalvm.polyglot.Engine$1.run(Engine.java:1067)
	at org.graalvm.polyglot.Engine$1.run(Engine.java:1061)
	at java.base/java.security.AccessController.doPrivileged(AccessController.java:319)
	at org.graalvm.polyglot.Engine.initEngineImpl(Engine.java:1061)
	at org.graalvm.polyglot.Engine$ImplHolder.<clinit>(Engine.java:143)
	at org.graalvm.polyglot.Engine.getImpl(Engine.java:367)
	at org.graalvm.polyglot.Engine$Builder.build(Engine.java:665)
	at org.pkl.core.runtime.VmUtils.<clinit>(VmUtils.java:74)
	at org.pkl.core.EvaluatorImpl.<init>(EvaluatorImpl.java:90)
	at org.pkl.core.EvaluatorBuilder.build(EvaluatorBuilder.java:489)
	at org.pkl.core.project.Project.loadFromPath(Project.java:89)
	at org.pkl.commons.cli.CliCommand.loadProject(CliCommand.kt:96)
	at org.pkl.commons.cli.CliCommand$project$2.invoke(CliCommand.kt:80)
	at org.pkl.commons.cli.CliCommand$project$2.invoke(CliCommand.kt:76)
	at kotlin.SynchronizedLazyImpl.getValue(LazyJVM.kt:74)
	at org.pkl.commons.cli.CliCommand.getProject(CliCommand.kt:76)
	at org.pkl.commons.cli.CliCommand$evaluatorSettings$2.invoke(CliCommand.kt:106)
	at org.pkl.commons.cli.CliCommand$evaluatorSettings$2.invoke(CliCommand.kt:105)
	at kotlin.SynchronizedLazyImpl.getValue(LazyJVM.kt:74)
	at org.pkl.commons.cli.CliCommand.getEvaluatorSettings(CliCommand.kt:105)
	at org.pkl.commons.cli.CliCommand.access$getEvaluatorSettings(CliCommand.kt:35)
	at org.pkl.commons.cli.CliCommand$allowedModules$2.invoke(CliCommand.kt:111)
	at org.pkl.commons.cli.CliCommand$allowedModules$2.invoke(CliCommand.kt:109)
	at kotlin.SynchronizedLazyImpl.getValue(LazyJVM.kt:74)
	at org.pkl.commons.cli.CliCommand.getAllowedModules(CliCommand.kt:109)
	at org.pkl.commons.cli.CliCommand$securityManager$2.invoke(CliCommand.kt:155)
	at org.pkl.commons.cli.CliCommand$securityManager$2.invoke(CliCommand.kt:153)
	at kotlin.SynchronizedLazyImpl.getValue(LazyJVM.kt:74)
	at org.pkl.commons.cli.CliCommand.getSecurityManager(CliCommand.kt:153)
	at org.pkl.doc.CliDocGenerator.<init>(CliDocGenerator.kt:40)
	at org.pkl.doc.DocCommand.run(Main.kt:72)
	at com.github.ajalt.clikt.parsers.Parser.parse(Parser.kt:198)
	at com.github.ajalt.clikt.parsers.Parser.parse(Parser.kt:18)
	at com.github.ajalt.clikt.core.CliktCommand.parse(CliktCommand.kt:400)
	at com.github.ajalt.clikt.core.CliktCommand.parse$default(CliktCommand.kt:397)
	at com.github.ajalt.clikt.core.CliktCommand.main(CliktCommand.kt:415)
	at com.github.ajalt.clikt.core.CliktCommand.main(CliktCommand.kt:440)
	at org.pkl.doc.Main$main$1.invoke(Main.kt:37)
	at org.pkl.doc.Main$main$1.invoke(Main.kt:37)
	at org.pkl.commons.cli.CliMainKt.cliMain(CliMain.kt:33)
	at org.pkl.doc.Main.main(Main.kt:37)

HT154 Feb 14, 2025

Pkl versions before 0.28.0 (so any currently released version) require JDK 17-21

kaihendry Feb 15, 2025
Author

Now I am hitting /~https://github.com/kaihendry/pkl-redis/actions/runs/13327152687/job/37222855536

[jbang] Resolving dependencies...
[jbang]    org.pkl-lang:pkl-doc:0.26.3
[jbang] Dependencies resolved
An unexpected error has occurred. Would you mind filing a bug report?

java.lang.StringIndexOutOfBoundsException: begin 13, end 7, length 7
	at java.base/java.lang.String.checkBoundsBeginEnd(String.java:4606)
	at java.base/java.lang.String.substring(String.java:2709)
	at java.base/java.lang.String.substring(String.java:26[8](/~https://github.com/kaihendry/pkl-redis/actions/runs/13327152687/job/37222855536#step:5:9)2)
	at org.pkl.doc.UtilKt.getModulePath(Util.kt:137)
	at org.pkl.doc.DocPackageInfo.getModuleImportUri$pkl_doc(DocPackageInfo.kt:163)
	at org.pkl.doc.DocPackage$docModules$2.invoke(DocGenerator.kt:182)
	at org.pkl.doc.DocPackage$docModules$2.invoke(DocGenerator.kt:174)
	at kotlin.SynchronizedLazyImpl.getValue(LazyJVM.kt:74)
	at org.pkl.doc.DocPackage.getDocModules(DocGenerator.kt:174)
	at org.pkl.doc.SiteScope$packageScopes$2.invoke(DocScope.kt:13[9](/~https://github.com/kaihendry/pkl-redis/actions/runs/13327152687/job/37222855536#step:5:10))
	at org.pkl.doc.SiteScope$packageScopes$2.invoke(DocScope.kt:134)
	at kotlin.SynchronizedLazyImpl.getValue(LazyJVM.kt:74)
	at org.pkl.doc.SiteScope.getPackageScopes(DocScope.kt:134)
	at org.pkl.doc.SiteScope.getPackage(DocScope.kt:190)
	at org.pkl.doc.HtmlGenerator.generate(HtmlGenerator.kt:33)
	at org.pkl.doc.DocGenerator.run(DocGenerator.kt:[10](/~https://github.com/kaihendry/pkl-redis/actions/runs/13327152687/job/37222855536#step:5:11)0)
	at org.pkl.doc.CliDocGenerator.doRun(CliDocGenerator.kt:273)
	at org.pkl.commons.cli.CliCommand.run(CliCommand.kt:44)
	at org.pkl.doc.DocCommand.run(Main.kt:72)
	at com.github.ajalt.clikt.parsers.Parser.parse(Parser.kt:198)
	at com.github.ajalt.clikt.parsers.Parser.parse(Parser.kt:18)
	at com.github.ajalt.clikt.core.CliktCommand.parse(CliktCommand.kt:400)
	at com.github.ajalt.clikt.core.CliktCommand.parse$default(CliktCommand.kt:397)
	at com.github.ajalt.clikt.core.CliktCommand.main(CliktCommand.kt:4[15](/~https://github.com/kaihendry/pkl-redis/actions/runs/13327152687/job/37222855536#step:5:16))
	at com.github.ajalt.clikt.core.CliktCommand.main(CliktCommand.kt:440)
	at org.pkl.doc.Main$main$1.invoke(Main.kt:37)
	at org.pkl.doc.Main$main$1.invoke(Main.kt:37)
	at org.pkl.commons.cli.CliMainKt.cliMain(CliMain.kt:33)
	at org.pkl.doc.Main.main(Main.kt:37)
Error: Process completed with exit code 1.

kaihendry · 2025-02-19T09:37:24Z

kaihendry
Feb 19, 2025
Author

When I try a newer version, jbang run --main org.pkl.doc.Main "org.pkl-lang:pkl-doc:0.27.2" control.pkl doc-package-info.pkl -o .out I hit another problem:

JAVA_HOME: /opt/hostedtoolcache/Java_Zulu_jdk/17.0.14-7/x64
    JAVA_HOME_17_X[6](/~https://github.com/kaihendry/pkl-redis/actions/runs/13409256927/job/37455409568#step:5:6)4: /opt/hostedtoolcache/Java_Zulu_jdk/17.0.14-7/x64
[jbang] Resolving dependencies...
[jbang]    org.pkl-lang:pkl-doc:0.2[7](/~https://github.com/kaihendry/pkl-redis/actions/runs/13409256927/job/37455409568#step:5:8).2
[jbang] Dependencies resolved
Error: Exception in thread "main" java.lang.NoClassDefFoundError: com/github/ajalt/clikt/core/CliktCommand
	at java.base/java.lang.ClassLoader.defineClass1(Native Method)
	at java.base/java.lang.ClassLoader.defineClass(ClassLoader.java:1017)
	at java.base/java.security.SecureClassLoader.defineClass(SecureClassLoader.java:150)
	at java.base/jdk.internal.loader.BuiltinClassLoader.defineClass(BuiltinClassLoader.java:[8](/~https://github.com/kaihendry/pkl-redis/actions/runs/13409256927/job/37455409568#step:5:9)62)
	at java.base/jdk.internal.loader.BuiltinClassLoader.findClassOnClassPathOrNull(BuiltinClassLoader

I think it's a Kotlin dependency issue, but I can't really work it out! /~https://github.com/kaihendry/pkl-redis/actions/runs/13409256927/job/37455409568

7 replies

stackoverflow Feb 27, 2025
Maintainer

It should be pretty simple to configure pkl-doc use gradle. Here's a build file a couple lines long: /~https://github.com/apple/pkl-jvm-examples/blob/main/pkldoc/build.gradle.kts

It is possible to generate a self contained jar for pkl-doc, but even if we do that the earliest that would be released is in 0.29 which is some months away.

StefMa Feb 27, 2025

The thing is that people don't want to use gradle at all. Honestly pkl is super lightweight and only for generating docs adding a full blown jvm tooling (gradle) is just overkill.

However since this is the most reliable tooling for docs generation so far, I also thought about creating a workflow that does the Gradle stuff "on the fly" to generate the docs.
So you won't have gradle in git but only "as a tool" on your CI.
Still not the best workflow but that is all we get so far...

pixlwave Feb 27, 2025

Can it please be made into a self-contained jar?

I'm struggling to understand how the gradle plugin works.

Copy their build.gradle.kts, gradlew and gradle (directory) seems so complex.

+1 on this. Today I've had to learn which JDK to install, what Maven is and how to install a package, where Maven actually installs packages as they're not in my path and now I'm getting java class errors which lead me here to see there is a lot more to learn. I appreciate this all good knowledge to pick up, but seems worth sharing that the experience could be much smoother if it was possible to brew install pkl-doc like you do for pkl and generate the docs via a CLI.

bioball Feb 27, 2025
Maintainer

Thanks for the feedback, and I agree. We'll look to publish pkldoc as a standalone executable in the next release.

pixlwave Feb 27, 2025

Wooo, thank you so much 🙏

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

How to generate docs via a Github workflow? #950

{{title}}

Replies: 2 comments 10 replies

{{title}}

{{title}}

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

Select a reply

How to generate docs via a Github workflow? #950

kaihendry Feb 13, 2025

Replies: 2 comments · 10 replies

StefMa Feb 13, 2025

kaihendry Feb 14, 2025 Author

HT154 Feb 14, 2025

kaihendry Feb 15, 2025 Author

kaihendry Feb 19, 2025 Author

stackoverflow Feb 27, 2025 Maintainer

StefMa Feb 27, 2025

pixlwave Feb 27, 2025

bioball Feb 27, 2025 Maintainer

pixlwave Feb 27, 2025

kaihendry
Feb 13, 2025

Replies: 2 comments 10 replies

StefMa
Feb 13, 2025

kaihendry Feb 14, 2025
Author

kaihendry Feb 15, 2025
Author

kaihendry
Feb 19, 2025
Author

stackoverflow Feb 27, 2025
Maintainer

bioball Feb 27, 2025
Maintainer