Publishing Projects with Docs & Shorter URLs

[jamesward]

I'm working trying to publish a very small Pkl project: https://github.com/jamesward/pklamper

I got the release with the metadata and zip published: https://github.com/jamesward/pklamper/releases/tag/v0.0.3
I'm using it: https://github.com/jamesward/grapkl/blob/main/build.gradle.pkl

But I'm not sure how to:

• Also publish the docs. Wasn't sure if I needed the doc-package-info.pkl file. Or what should go in the pkldocGenerators gradle config.
• What should be done to setup better URLs like package://jamesward.github.com/[email protected]#/project.pkl instead of the GitHub release URL like package://github.com/jamesward/pklamper/releases/download/v0.0.3/[email protected]#/project.pkl

Thanks for any pointers / examples!

[madisp]

I also recently investigated publishing. I haven't setup docs yet, but for a shorter URL you'll need an actual redirect from the URL.

This is how pkg.pkl-lang.org works, it looks like https://pkg.pkl-lang.org/\(repo)/\(package)@\(version) redirects to GitHub downloads:

$ curl -v "https://pkg.pkl-lang.org/pkl-k8s/[email protected]" 2>&1 | grep "location: "
< location: https://github.com/apple/pkl-k8s/releases/download/[email protected]/[email protected]

$ curl -v "https://pkg.pkl-lang.org/someRepo/[email protected]" 2>&1 | grep "location: "
< location: https://github.com/apple/someRepo/releases/download/[email protected]/[email protected]

[madisp]

I replicated this setup with my first package as well: https://madis.pink/pkl/\(release)@\(version) redirects to madisp/pkl-schemas GitHub repository and it works well.

[stackoverflow]

If you publish your packages as GitHub releases, you can use pkg.pkl-lang.org to reference them.

For example, if your release is published to repo github.com/foo/bar, you can use package://pkg.pkl-lang.org/github.com/foo/bar as your base path.

For this to work, the release tag needs to match the metadata of the package ([email protected] in your case).

In your case, you can use https://pkg.pkl-lang.org/github.com/jamesward/pklamper/[email protected]
Which will redirect to https://github.com/jamesward/pklamper/releases/download/[email protected]/[email protected]

[jamesward]

Oh that is cool that you setup the forwards for all GitHub :) I'll adjust my tags to not have the v prefix so I can use this :)

[bioball]

Hey @jamesward, hold off on this real quick; we're going to change the redirect (maybe to pkg.pkl-lang.org/github.com)

[bioball]

Update here: it's now set up! I've updated @stackoverflow's answer above.

[James-Ansley]

Can the same pkg.pkl-lang.org/github.com style URL be used for the packageZipUrl field? Or does that need to directly reference the https://github.com/<repo>/releases/download/<tag>/<pkg>.zip URL?

[stackoverflow]

You should use the actual GitHub url for the zip file, for example:

package {
  name = <packageName>
  version = <version>
  packageZipUrl = "https://github.com/<your_org>/<your_repo>/releases/download/\(name)@\(version)/\(name)@\(version).zip"
}

[bioball]

For generating pkldoc:

You only need a doc-package-info.pkl if you expect to use another import mechanism to do importing. If you are publishing as a package, you can skip that, because it gets derived from your PklProject.

To publish documentation, just specify the package URI in your sourceModules.

For example, this generates pkldoc for our TOML package:

pkl {
  pkldocGenerators {
    register("pkldoc") {
      sourceModules.set(listOf(uri("package://pkg.pkl-lang.org/pkl-pantry/[email protected]")))
    }
  }
}

Note that when generating documentation, every module of a package must have a correct module name. The module name should be <packageName>.<path>.<to>.<filename>. For example, module foo/bar/baz.pkl in a package called "mypackage" should have module mypackage.foo.bar.baz in its module header. The package name is what you set as package.name in your PklProject.

[jamesward]

Thank you! I'll give this a try.

[jamesward]

I was able to get the PklDoc generation working and automated! Here is the generated site:
https://jamesward.github.io/pklgha

The Pkl that does the work:
https://github.com/jamesward/pklgha/blob/main/src/GitHubActionPklRelease.pkl

Thanks for all the help!

Note that I'd like to figure out how to get versioned docs as part of this.