Pkldoc: Landing page is empty #311

New Issue

2025-12-30T01:23:26+01:00

adam commented

2025-12-30 01:23:26 +01:00

Originally created by @StefMa on GitHub (Jun 3, 2025).

Given my pkl-gha project.
I want to gernate the pkldocs for the current code.
For this, because the pkl-doc fat jar package fais with an exception, I use the Gradle plugin like the following:

plugins {
    id("org.pkl-lang") version "0.28.2"
}

val maybeVersion = "0.0.4"

pkl {
    project {
        packagers {
            register("makePackages") {
                if (maybeVersion != null) {
                    environmentVariables.put("VERSION", maybeVersion)
                }
                projectDirectories.from(file("."))
            }
        }
    }
    // ./gradlew pkldoc
    if (maybeVersion != null) {
        pkldocGenerators {
            register("pkldoc") {
                sourceModules =
                    files(
                        "doc-package-info.pkl",
                        "Workflow.pkl",
                        "Context.pkl",
                    )
            }
        }
    }
}

The doc-package-info.pkl looks like this:

/// Write GitHub Action Workflows with Pkl
amends "pkl:DocPackageInfo"

name = "com.github.action"
version = "0.0.4-SNAPSHOT"
importUri = "package://pkg.pkl-lang.org/github.com/stefma/pkl-gha/com.github.action@\(version)/"
issueTracker = "https://github.com/stefma/pkl-gha/issues"
sourceCode = "https://github.com/stefma/pkl-gha"
authors { "Stefan M. <StefMaDev@outlook.com>" }

The rest of the code is untouched from this tree:
https://github.com/StefMa/pkl-gha/tree/dd7b6049566130609ceb983dca059fed16c41f3d

If I runing ./gradlew pkldoc and open the build/pkldoc/pkldoc/index.html I see a blank site:

However, the sub-package com.github.action exists:
http://localhost:63342/pkl-github/build/pkldoc/pkldoc/com.github.action/0.0.4-SNAPSHOT/index.html

If I change the build.gradle using my already published package:

                sourceModules =
+                   listOf(uri("package://pkg.pkl-lang.org/github.com/stefma/pkl-gha/com.github.action@$maybeVersion"))
-                    files(
-                        "doc-package-info.pkl",
-                        "Workflow.pkl",
-                        "Context.pkl",
-                   )

then the landing page is generated correctly 🫠

Looking at the generated files, there is a slighly difference.
I observe the the "host" is missing in the local files version... 🤔
The first image displays the "lokal files" version, the second one the uri (remote) file version

I'm not sure if this is an bug in pkldoc or if I holding it wrong.
Maybe, for some strange reasions, this might be even the expected behavior 🤷
I appreciate any help here 🙂

Originally created by @StefMa on GitHub (Jun 3, 2025). Given my [pkl-gha project](https://github.com/StefMa/pkl-gha/). I want to gernate the pkldocs for the *current* code. For this, because the `pkl-doc` fat jar package fais with an exception, I use the Gradle plugin like the following: ```kotlin plugins { id("org.pkl-lang") version "0.28.2" } val maybeVersion = "0.0.4" pkl { project { packagers { register("makePackages") { if (maybeVersion != null) { environmentVariables.put("VERSION", maybeVersion) } projectDirectories.from(file(".")) } } } // ./gradlew pkldoc if (maybeVersion != null) { pkldocGenerators { register("pkldoc") { sourceModules = files( "doc-package-info.pkl", "Workflow.pkl", "Context.pkl", ) } } } } ``` The `doc-package-info.pkl` looks like this: ```pkl /// Write GitHub Action Workflows with Pkl amends "pkl:DocPackageInfo" name = "com.github.action" version = "0.0.4-SNAPSHOT" importUri = "package://pkg.pkl-lang.org/github.com/stefma/pkl-gha/com.github.action@\(version)/" issueTracker = "https://github.com/stefma/pkl-gha/issues" sourceCode = "https://github.com/stefma/pkl-gha" authors { "Stefan M. <StefMaDev@outlook.com>" } ``` The rest of the code is untouched from this tree: https://github.com/StefMa/pkl-gha/tree/dd7b6049566130609ceb983dca059fed16c41f3d If I runing `./gradlew pkldoc` and open the `build/pkldoc/pkldoc/index.html` I see a blank site: ![Image](https://github.com/user-attachments/assets/c8706ff2-2cb7-46d0-ba28-c9bc91624b35) However, the sub-package `com.github.action` exists: http://localhost:63342/pkl-github/build/pkldoc/pkldoc/com.github.action/0.0.4-SNAPSHOT/index.html ![Image](https://github.com/user-attachments/assets/9247919a-a48b-491a-a0aa-8b868b5c5b44) If I change the `build.gradle` using my already published package: ```diff sourceModules = + listOf(uri("package://pkg.pkl-lang.org/github.com/stefma/pkl-gha/com.github.action@$maybeVersion")) - files( - "doc-package-info.pkl", - "Workflow.pkl", - "Context.pkl", - ) ``` *then* the landing page is generated correctly 🫠 ![Image](https://github.com/user-attachments/assets/1b338f62-9a34-4429-8255-2281f2ab26d1) Looking at the generated files, there is a slighly difference. I observe the the "host" is missing in the local files version... 🤔 The first image displays the "lokal files" version, the second one the `uri` (remote) file version ![Image](https://github.com/user-attachments/assets/f687c85f-d413-47a2-872a-35acf714a907)![Image](https://github.com/user-attachments/assets/20f2b68d-c1c3-4b27-bd37-7cdabc756d04) I'm not sure if this is an bug in pkldoc or if I holding it wrong. Maybe, for some strange reasions, this might be even the expected behavior 🤷 I appreciate any help here 🙂

adam closed this issue

2025-12-30 01:23:26 +01:00

adam commented

2025-12-30 01:23:27 +01:00

@bioball commented on GitHub (Jun 3, 2025):

This is because versions with pre-release identifiers aren't indexed. They don't show up on the package index page, and they also don't show up in search.

Try publishing an initial version without a pre-release. That package will then show up on the index page. After that, you can publish a new version with a pre-release identifier, and that pre-release version will show up on the list of versions when you're browsing the package page.

By the way, SNAPSHOT is a maven-ism, and uncommon in semver. For semver, I'd recommend alpha, beta, etc.

@bioball commented on GitHub (Jun 3, 2025): This is because versions with pre-release identifiers aren't indexed. They don't show up on the package index page, and they also don't show up in search. Try publishing an initial version without a pre-release. That package will then show up on the index page. After that, you can publish a new version with a pre-release identifier, and that pre-release version will show up on the list of versions when you're browsing the package page. By the way, `SNAPSHOT` is a maven-ism, and uncommon in semver. For semver, I'd recommend `alpha`, `beta`, etc.

adam commented

2025-12-30 01:23:27 +01:00

@StefMa commented on GitHub (Jun 3, 2025):

Thanks for the answer. But... I am not sure if I understand it correctly. I do need to publish a version so that I can create the pkldoc for my current code? 🤔 I don't want to create the docs based on a public version. I want to create the docs based on the current "dev setup"... 🤔 Isn't this what we should do? 🤔
Is pkl more designed to create docs based on a published version?

Thanks for the semver hint! Will change that 🙃

@StefMa commented on GitHub (Jun 3, 2025): Thanks for the answer. But... I am not sure if I understand it correctly. I do need to publish a version so that I can create the pkldoc for my **current code**? 🤔 I don't want to create the docs based on a public version. I want to create the docs based on the current "dev setup"... 🤔 Isn't this what we should do? 🤔 Is pkl more designed to create docs based on a published version? Thanks for the semver hint! Will change that 🙃

adam commented

2025-12-30 01:23:27 +01:00

@bioball commented on GitHub (Jun 3, 2025):

Basically, try changing version 0.0.4-SNAPSHOT to 0.0.4, and you should see your package in the landing page.

@bioball commented on GitHub (Jun 3, 2025): Basically, try changing version `0.0.4-SNAPSHOT` to `0.0.4`, and you should see your package in the landing page.

adam commented

2025-12-30 01:23:28 +01:00

@StefMa commented on GitHub (Jun 4, 2025):

🤦 Thanks. That indeed solves it.

@StefMa commented on GitHub (Jun 4, 2025): 🤦 Thanks. That indeed solves it.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/pkl#311