Skip to content

Commit 5d90cf8

Browse files
bioballbioball
authored
Introduce pkl-doc model version 2 (#1169)
Currently, in order to update a pkl-doc documentation site, almost the entire existing site is read in order to update metadata like known versions, known subtypes, and more. For example, adding a new version of a package requires that the existing runtime data of all existing versions be updated. Eventually, this causes the required storage size to balloon exponentially to the number of versions. This addresses these limitations by: 1. Updating the runtime data structure to move "known versions" metadata to the package level (the same JSON file is used for all versions). 2. Eliminating known subtype and known usage information at a cross-package level. 3. Generating the search index by consuming the previously generated search index. 4. Generating the main page by consuming the search index. Because this changes how runtime data is stored, an existing docsite needs to be migrated. This also introduces a new migration command, `pkl-doc --migrate`, which transforms an older version of the website into a newer version.
1 parent 63f89fb commit 5d90cf8

File tree

1,599 files changed

+129995
-584
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

1,599 files changed

+129995
-584
lines changed

‎buildSrc/src/main/kotlin/pklFatJar.gradle.kts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ val relocations =
6060
// pkl-doc dependencies
6161
"org.commonmark." to "org.pkl.thirdparty.commonmark.",
6262
"org.jetbrains." to "org.pkl.thirdparty.jetbrains.",
63+
"_COROUTINE." to "org.pkl.thirdparty.kotlinx._COROUTINE.",
6364

6465
// pkl-config-java dependencies
6566
"io.leangen.geantyref." to "org.pkl.thirdparty.geantyref.",
@@ -99,6 +100,8 @@ tasks.shadowJar {
99100
exclude("META-INF/maven/**")
100101
exclude("META-INF/upgrade/**")
101102

103+
exclude("DebugProbesKt.bin")
104+
102105
val info = project.extensions.getByType<BuildInfo>()
103106
val minimumJvmTarget = JavaVersion.toVersion(info.jvmTarget)
104107

‎gradle/libs.versions.toml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ kotlin = "2.0.21"
3434
kotlinPoet = "1.6.+"
3535
kotlinxHtml = "0.11.0"
3636
kotlinxSerialization = "1.8.0"
37+
kotlinxCoroutines = "1.+"
3738
ktfmt = "0.53"
3839
# replaces nuValidator's log4j dependency
3940
# something related to log4j-1.2-api is apparently broken in 2.17.2
@@ -79,6 +80,7 @@ kotlinScripting = { group = "org.jetbrains.kotlin", name = "kotlin-scripting-jsr
7980
kotlinStdLib = { group = "org.jetbrains.kotlin", name = "kotlin-stdlib-jdk8", version.ref = "kotlin" }
8081
kotlinxHtml = { group = "org.jetbrains.kotlinx", name = "kotlinx-html-jvm", version.ref = "kotlinxHtml" }
8182
kotlinxSerializationJson = { group = "org.jetbrains.kotlinx", name = "kotlinx-serialization-json", version.ref = "kotlinxSerialization" }
83+
kotlinxCoroutinesCore = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-core", version.ref = "kotlinxCoroutines" }
8284
log4j12Api = { group = "org.apache.logging.log4j", name = "log4j-1.2-api", version.ref = "log4j" }
8385
msgpack = { group = "org.msgpack", name = "msgpack-core", version.ref = "msgpack" }
8486
nuValidator = { group = "nu.validator", name = "validator", version.ref = "nuValidator" }

‎pkl-commons-cli/src/main/kotlin/org/pkl/commons/cli/CliException.kt‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,9 +26,13 @@ open class CliException(
2626
*/
2727
message: String,
2828

29+
/** The cause */
30+
cause: Throwable?,
31+
2932
/** The process exit code to use. */
3033
val exitCode: Int = 1,
31-
) : RuntimeException(message) {
34+
) : RuntimeException(message, cause) {
35+
constructor(message: String, exitCode: Int = 1) : this(message, null, exitCode)
3236

3337
override fun toString(): String = message!!
3438
}
@@ -41,7 +45,11 @@ class CliBugException(
4145
/** The process exit code to use. */
4246
exitCode: Int = 1,
4347
) :
44-
CliException("An unexpected error has occurred. Would you mind filing a bug report?", exitCode) {
48+
CliException(
49+
"An unexpected error has occurred. Would you mind filing a bug report?",
50+
theCause,
51+
exitCode,
52+
) {
4553

4654
override fun toString(): String = "$message\n\n${theCause.printStackTraceToString()}"
4755
}

‎pkl-commons-test/src/main/files/packages/[email protected]/[email protected]‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
{
2+
"schemaVersion": 1,
3+
"name": "birds",
4+
"packageUri": "package://localhost:0/[email protected]",
5+
"packageZipUrl": "https://localhost:0/[email protected]/[email protected]",
6+
"dependencies": {
7+
"fruities": {
8+
"uri": "package://localhost:0/[email protected]",
9+
"checksums": {
10+
"sha256": "8d982761d182f2185e4180c82190791d9a60c721cb3393bb2e946fab90131e8c"
11+
}
12+
}
13+
},
14+
"version": "0.6.0",
15+
"packageZipChecksums": {
16+
"sha256": "$computedChecksum"
17+
},
18+
"sourceCodeUrlScheme": "https://example.com/birds/v0.6.0/blob%{path}#L%{line}-L%{endLine}",
19+
"sourceCode": "https://example.com/birds",
20+
"documentation": "https://example.com/bird-docs",
21+
"license": "UNLICENSED",
22+
"authors": [
23+
"[email protected]",
24+
"[email protected]"
25+
],
26+
"issueTracker": "https://example.com/birds/issues"
27+
}

‎pkl-commons-test/src/main/files/packages/[email protected]/package/Bird.pkl‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
open module birds.Bird
2+
3+
import "@fruities/Fruit.pkl"
4+
5+
name: String
6+
7+
favoriteFruit: Fruit

‎pkl-commons-test/src/main/files/packages/[email protected]/package/allFruit.pkl‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
module birds.allFruit
2+
3+
fruit = import*("@fruities/catalog/*.pkl")
4+
fruitFiles = read*("@fruities/catalog/*.pkl")

‎pkl-commons-test/src/main/files/packages/[email protected]/package/catalog.pkl‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
module birds.catalog
2+
3+
catalog = import*("catalog/*.pkl")
4+
catalogFiles = read*("catalog/*.pkl")

‎pkl-commons-test/src/main/files/packages/[email protected]/package/catalog/Ostrich.pkl‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
amends "../Bird.pkl"
2+
3+
name = "Ostrich"
4+
5+
favoriteFruit {
6+
name = "Orange"
7+
}

‎pkl-commons-test/src/main/files/packages/[email protected]/package/catalog/Swallow.pkl‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
amends "../Bird.pkl"
2+
3+
import "@fruities/catalog/apple.pkl"
4+
5+
name = "Swallow"
6+
7+
favoriteFruit = apple

‎pkl-commons-test/src/main/files/packages/[email protected]/package/some/dir/Bird.pkl‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
amends "..."
2+
3+
name = "Bird"
4+
5+
favoriteFruit {
6+
name = "Fruit"
7+
}

0 commit comments

Comments
 (0)