NOTE: A doc package is a way to generate documentation for modules that are not published
via the Project.Package mechanism.
Packages published via the Project.Package mechanism can have their documentation
generated directly by passing the resulting Package URI into Pkldoc.
A documentation package is a set of related modules that are versioned together.
Each package must have a descriptor that
amends this template
is named doc-package-info.pkl
is passed to the pkldoc command together with the modules to generate documentation for.
Each module to generate documentation must declare a module name that starts with a package name.
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.Birds.Parrot
is expected to exist at path Birds/Parrot.pkl within the package root.
A typical descriptor for a package looks as follows:
/// The overview documentation for this package.
/// The first paragraph is the mandatory _summary_.
/// Try to keep the summary short; a single sentence is common.
///
/// Subsequent paragraphs are separated by an empty line and collapsed by default.
/// They can use *Markdown syntax* and Pkldoc links such as [String].
amends "pkl:DocPackageInfo"
name = "com.example.Birds"
importUri = "https://example.com/Birds"
authors { "pigeon@example.com" }
sourceCode = "https://github.com/apple/birds/"
sourceCodeUrlScheme = "https://github.com/apple/birds/blob/\(version)%{path}#L%{line}-%{endLine}"
issueTracker = "https://github.com/apple/birds/issues"
version = "1.7.0"
Module import URIs are constructed from this URI as follows:
"\(importUri)\(modulePath)" where modulePath is
moduleName.removePrefix(name).replaceAll(".", "/").
For example, if package name is foo.bar and module name is foo.bar.baz.qux,
then modulePath is baz/qux.
The web URL of the source code for this package version.
The following placeholders are available:
%{path}
absolute file path of the file to open
%{line}
start line number to navigate to
%{endLine}
end line number to navigate to
The %{path} placeholder is derived from the module's name relative to the package name.
The module's name is expected to be prefixed by the package name.
In Pkl terms, path can be thought of as
"/" + moduleName.replaceFirst(packageName).replaceAll(".", "/") + ".pkl".
For example, if package name is foo.bar and module name is foo.bar.baz.qux,
then %{path} is /baz/qux.pkl.
Returns the relative, descendent directory path between this module and other.
Throws if no such path exists.
For example, if module mod1 has path /dir1/mod1.pkl, and module mod2 has path /dir1/dir2/dir3/mod2.pkl,
then mod1.relativePathTo(mod2) will return List("dir2", "dir3").
A common use case is to compute the directory path between a template located at the root of a hierarchy
(say rootModule.pkl) and the currently evaluated module (accessible via the module keyword):
Template for doc-package-info.pkl, the descriptor for a package.