Pkldoc

Pkldoc is a documentation website generator that produces navigable and searchable API documentation for Pkl modules.

Pkldoc’s look and feel is inspired by Scaladoc. To get a first impression, browse the Standard Library API Docs.

Features

Pkldoc offers the following features:

Code navigation

Easily navigate between hyperlinked modules, classes, functions, and properties.

Member search

Search the entire documentation by member name. See the next section for details.

Comment folding

Expand and collapse multi-paragraph doc comments.

Markdown support

Write doc comments in Markdown. See Doc Comments for details.

Member links

Link to other members from your doc comments. See Member Links for details.

Member anchors

Get a member’s deep link by clicking its anchor symbol and copying the URL in the address bar.

Cross-site links

Enable cross-site member links simply by providing the URLs of other Pkldoc websites such as the standard library docs.

To get a first impression of Pkldoc’s member search, let’s try and find property MinFiniteFloat in the standard library docs:

pkldoc search
Figure 1. Searching the standard library docs.

To start a search, press s. Search results are displayed as you type.

To limit the search to a particular kind of member, prefix the search term with m: for modules, c: for classes, f: for functions, or p: for properties. For example, search term p:min finds property MinFiniteFloat but not function min().

Camel case matching is always enabled and does not require capitalizing the search term. For example, search term mff matches properties MinFiniteFloat and MaxFiniteFloat.

Both search terms and member names may contain non-ASCII Unicode characters. As characters are normalized to their base form, search term res matches Réseau.

The @AlsoKnownAs annotation, defined and used throughout the pkl.base module, documents alternative names for a member used in other programming languages or earlier versions of a module. Pkldoc’s search takes these alternative names into account. For example, searching the standard library docs for count or size finds property String.length. Feel free to use @AlsoKnownAs in your own modules.

Search results are categorized into exact and other (partial) matches. On module and class pages, additional categories show matches in the same module and class. Within a category, results are ranked by similarity with the search term.

To navigate to a search result, either click the result or select it with the up/down arrow keys and press Enter.

Installation

Pkldoc is offered as Gradle plugin, Java library, and CLI.

Gradle Plugin

See Installation in the Gradle Plugin chapter.

Java Library

The pkl-doc library is available from Maven Central. It requires Java 11 or higher.

Gradle

To use the library in a Gradle project, declare the following dependency:

  • Groovy

  • Kotlin

build.gradle
dependencies {
  compile "org.pkl-lang:pkl-doc:0.25.3"
}

repositories {
  mavenCentral()
}
build.gradle.kts
dependencies {
  compile("org.pkl-lang:pkl-doc:0.25.3")
}

repositories {
  mavenCentral()
}

Maven

To use the library in a Maven project, declare the following dependency:

pom.xml
<project>
  <dependency>
    <groupId>org.pkl-lang</groupId>
    <artifactId>pkl-doc</artifactId>
    <version>0.25.3</version>
  </dependency>
</project>

CLI

The CLI is bundled with the library and does not currently ship as a native executable or a self-contained Jar. We recommend to provision it with a Maven compatible build tool as shown in Library Installation.

Usage

The Pkldoc tool is offered as Gradle plugin, Java library, and CLI. It can generate documentation either for modules directly, or generate documentation for package uris.

The tool requires an argument of a module named _docsite-info.pkl, that amends pkl.DocsiteInfo.

Generating documentation for modules directly

Modules can be passed directly to Pkldoc for documentation generation. When generating documentation for these modules, there must also be a module named doc-package-info.pkl that amends pkl.DocPackageInfo.

The doc-package-info.pkl module defines a doc package, which describes how modules are grouped and versioned together.

When generating documentation for modules, each such module must declare a module name that starts with a package name declared in a doc-package-info.pkl module. For example, the following are valid module declarations for package com.example:

  • module com.example.Birds

  • module com.example.Birds.Parrot

The part of the module name that comes after the package name must match the module’s relative path in its source code repository. For example, module com.example.Bird.Parrot is expected to be found at $sourceCode/Bird/Parrot.pkl, where sourceCode is configured in doc-package-info.pkl.

Generating documentation for a package

Pkldoc can alternatively generate documentation for a package. When generating documentation for a package, the URI of the package must be passed as an argument to Pkldoc. These packages must already be published and downloadable.

When generating documentation for packages, modules within a package must declare a module name that is prefixed by the package’s name declared in the Package.name property of its PklProject file. For example, the following are valid module declarations for package com.example:

  • module com.example.Birds

  • module com.example.Birds.Parrot

The part of the module name that comes after the package name must match the module’s relative path in its source code repository. For example, module com.example.Bird.Parrot is expected to be found at $sourceCode/Bird/Parrot.pkl, where sourceCode is configured in the Package.sourceCode property of its PklProject file.

Gradle Plugin

See Pkldoc Generation in the Gradle Plugin chapter.

Java Library

The Java library offers two APIs:

  • A high-level CliDocGenerator API whose feature set corresponds to the CLI.

  • A low-level DocGenerator API that offers additional features and control.

For more information, refer to the Javadoc documentation.

CLI

As mentioned in CLI Installation, the CLI is bundled with the library. To run the CLI, execute the library Jar or its org.pkl.doc.Main class.

Synopsis: java -cp <classpath> -jar pkl-doc.jar [<options>] <modules>

<modules>

The absolute or relative URIs of docsite descriptors, package descriptors, and the modules for which to generate documentation.

Relative URIs are resolved against the working directory.

Options

-o, --output-dir

Default: (none)
Example: pkldoc The directory where generated documentation is placed.

Common CLI options:

--allowed-modules

Default: pkl:,file:,modulepath:,https:,repl:,package:,projectpackage:
Comma-separated list of URI patterns that determine which modules can be loaded and evaluated. Patterns are matched against the beginning of module URIs. (File paths have been converted to file: URLs at this stage.) At least one pattern needs to match for a module to be loadable. Both source modules and transitive modules are subject to this check.

--allowed-resources

Default: env:,prop:,package:,projectpackage:
Comma-separated list of URI patterns that determine which external resources can be read. Patterns are matched against the beginning of resource URIs. At least one pattern needs to match for a resource to be readable.

--cache-dir

Default: ~/.pkl/cache
Example: /path/to/module/cache/
The cache directory for storing packages.

--no-cache

Disable cacheing of packages.

-e, --env-var

Default: OS environment variables for the current process
Example: MY_VAR=myValue
Sets an environment variable that can be read by Pkl code with read("env:<envVarName>"). Repeat this option to set multiple environment variables.

-h, --help

Display help information.

--module-path

Default: (empty)
Example: dir1:zip1.zip:jar1.jar
Directories, ZIP archives, or JAR archives to search when resolving modulepath: URIs. Paths are separated by the platform-specific path separator (: on *nix, ; on Windows). Relative paths are resolved against the working directory.

-p, --property

Default: (none)
Example: myProp=myValue
Sets an external property that can be read by Pkl code with read("prop:<propertyName>"). Repeat this option to set multiple external properties.

--root-dir

Default: (none)
Example: /some/path
Root directory for file: modules and resources. If set, access to file-based modules and resources is restricted to those located under the specified root directory. Any symlinks are resolved before this check is performed.

--settings

Default: (none)
Example: mySettings.pkl
File path of the Pkl settings file to use. If not set, ~/.pkl/settings.pkl or defaults specified in the pkl.settings standard library module are used.

-t, --timeout

Default: (none)
Example: 30
Duration, in seconds, after which evaluation of a source module will be timed out. Note that a timeout is treated the same as a program error in that any subsequent source modules will not be evaluated.

-v, --version

Display version information.

-w, --working-dir

Base path that relative module paths passed as command-line arguments are resolved against. Defaults to the current working directory.

--ca-certificates

Default: (none)
Example: /some/path/certificates.pem
Path to a file containing CA certificates to be used for TLS connections.

Setting this option replaces the existing set of CA certificates bundled into the CLI. Certificates need to be X.509 certificates in PEM format.

For other methods of configuring certificates, see CA Certificates.

Full Example

For a ready-to-go example with full source code and detailed walkthrough, see pkldoc in the pkl/pkl-examples repository.