starred/pkl
1
0
Fork 0
mirror of https://github.com/apple/pkl.git synced 2026-01-11 06:10:40 +01:00
Code Issues 198 Packages Projects Releases 10 Wiki Activity

How to generate stdlib documentation? #347

New Issue
Open
opened 2025-12-30 01:23:43 +01:00 by adam · 2 comments
adam commented 2025-12-30 01:23:43 +01:00
Owner
Copy Link

Originally created by @sin-ack on GitHub (Oct 1, 2025).

I'm trying to use pkl-doc to generate documentation from a local branch I have of pkl, but when trying to point pkl-doc at stdlib/, I get:

 » pkl-doc/build/executable/pkldoc-linux-amd64 stdlib/*.pkl --output-dir stdlib-docs
–– Pkl Error ––
External members can only be defined by standard library modules.

175 | external function run(): BenchmarkResult
      ^^^^^^^^
at pkl.Benchmark#Microbenchmark (file:///home/agni/repos/third-party/pkl/stdlib/Benchmark.pkl, line 175)

How can I generate a local copy of the stdlib docs? DEVELOPMENT.adoc doesn't mention it either.

Originally created by @sin-ack on GitHub (Oct 1, 2025). I'm trying to use `pkl-doc` to generate documentation from a local branch I have of pkl, but when trying to point `pkl-doc` at `stdlib/`, I get: ``` » pkl-doc/build/executable/pkldoc-linux-amd64 stdlib/*.pkl --output-dir stdlib-docs –– Pkl Error –– External members can only be defined by standard library modules. 175 | external function run(): BenchmarkResult ^^^^^^^^ at pkl.Benchmark#Microbenchmark (file:///home/agni/repos/third-party/pkl/stdlib/Benchmark.pkl, line 175) ``` How can I generate a local copy of the stdlib docs? `DEVELOPMENT.adoc` doesn't mention it either.
adam commented 2025-12-30 01:23:44 +01:00
Author
Owner
Copy Link

@bioball commented on GitHub (Oct 17, 2025):

You need to use the lower-level API to do this; i.e. call into org.pkl.doc.DocGenerator with the standard library as one of the packages arguments. You'd collect the schemas with the Pkl evaluator's evaluateSchema method, passing in each of the stdlib modules.

But: the stdlib documentation already exists here: https://pkl-lang.org/package-docs/pkl/current/index.html. Why are you looking to generate docs for the stdlib?

@bioball commented on GitHub (Oct 17, 2025): You need to use the lower-level API to do this; i.e. call into `org.pkl.doc.DocGenerator` with the standard library as one of the `packages` arguments. You'd collect the schemas with the Pkl evaluator's `evaluateSchema` method, passing in each of the stdlib modules. But: the stdlib documentation already exists here: https://pkl-lang.org/package-docs/pkl/current/index.html. Why are you looking to generate docs for the stdlib?
adam commented 2025-12-30 01:23:44 +01:00
Author
Owner
Copy Link

@sin-ack commented on GitHub (Oct 19, 2025):

The package-docs currently doesn't contain documentation built regularly from main, and we're currently internally using a branch on top of main (binary parser/renderer + some Pkldoc fixes) which makes Pkldoc output links to "0.30.0-dev". I wanted to include stdlib documentation in our internal docs site as well to make cross-links to stdlib types work.

@sin-ack commented on GitHub (Oct 19, 2025): The package-docs currently doesn't contain documentation built regularly from `main`, and we're currently internally using a branch on top of `main` (binary parser/renderer + some Pkldoc fixes) which makes Pkldoc output links to "0.30.0-dev". I wanted to include stdlib documentation in our internal docs site as well to make cross-links to stdlib types work.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
duplicate
enhancement
good first issue
help wanted
pull-request
Mirrored from GitHub Pull Request
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/pkl#347
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?