Store PklProject annotations in the project metadata (#708)

Write annotations to project metadata, and provide them to pkl-doc\

The following annotations have meaning for pkl-doc:
* `@Unlisted`: hide package from documentation site
* `@Deprecated`: add deprecated information
This commit is contained in:
Islon Scherer
2024-10-25 02:21:58 +02:00
committed by GitHub
parent 93cc3253eb
commit 8b0118fec5
22 changed files with 976 additions and 17 deletions

View File

@@ -108,7 +108,8 @@ class CliDocGenerator(private val options: CliDocGeneratorOptions) : CliCommand(
overview = metadata.description,
extraAttributes = mapOf("Checksum" to checksum.sha256),
sourceCode = metadata.sourceCode,
sourceCodeUrlScheme = metadata.sourceCodeUrlScheme
sourceCodeUrlScheme = metadata.sourceCodeUrlScheme,
annotations = metadata.annotations,
)
}

View File

@@ -0,0 +1 @@
runtimeData.links('known-versions','[{"text":"1.0.0","classes":"current-version"}]');

View File

@@ -0,0 +1 @@
runtimeData.links('known-versions','[{"text":"1.0.0","classes":"current-version"}]');

View File

@@ -118,6 +118,18 @@ age: Int
</div>
</div>
</li>
<li>
<div id="localhost:0%2Fdeprecated" class="anchor"> </div>
<div class="member with-page-link"><a class="member-selflink material-icons" href="#localhost:0%2Fdeprecated">link</a>
<div class="member-left">
<div class="member-modifiers member-deprecated">package </div>
</div>
<div class="member-main">
<div class="member-signature member-deprecated"><a class="name-decl" href="./localhost(3a)0/deprecated/current/index.html">localhost:0/deprecated</a></div>
<div class="doc-comment">Deprecated: don't use</div>
</div>
</div>
</li>
<li>
<div id="localhost:0%2Ffruit" class="anchor"> </div>
<div class="member with-page-link"><a class="member-selflink material-icons" href="#localhost:0%2Ffruit">link</a>

View File

@@ -0,0 +1,219 @@
<!DOCTYPE html>
<html>
<head>
<title>deprecated (localhost:0/deprecated:1.0.0) • Docsite Title</title>
<script src="../../../../scripts/pkldoc.js" defer="defer"></script>
<script src="../../../../scripts/scroll-into-view.min.js" defer="defer"></script>
<script src="../../../../data/localhost(3a)0/deprecated/1.0.0/deprecated/index.js" defer="defer"></script>
<link href="../../../../styles/pkldoc.css" media="screen" type="text/css" rel="stylesheet">
<link rel="icon" type="image/svg+xml" href="../../../../images/favicon.svg">
<link rel="apple-touch-icon" sizes="180x180" href="../../../../images/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="../../../../images/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="../../../../images/favicon-16x16.png">
<meta charset="UTF-8">
</head>
<body onload="onLoad()">
<header>
<div id="doc-title"><a href="../../../../index.html">Docsite Title</a></div>
<div id="search"><i id="search-icon" class="material-icons">search</i><input id="search-input" type="search" placeholder="Click or press 'S' to search this package" autocomplete="off" data-package-name="localhost:0/deprecated" data-package-version="1.0.0" data-package-url-prefix="../" data-module-name="deprecated.deprecated" data-root-url-prefix="../../../../"></div>
</header>
<main><a class="declaration-parent-link" href="../../../../index.html">Docsite Title</a> &gt; <a class="declaration-parent-link" href="../index.html">localhost:0/deprecated</a>
<h1 id="declaration-title">deprecated.deprecated<span id="declaration-version">1.0.0</span></h1>
<ul class="member-group-links">
<li><a href="#_properties">Properties</a></li>
<li><a href="#_methods">Methods</a></li>
</ul>
<div id="_overview" class="anchor"> </div>
<div id="_declaration" class="member">
<div class="member-signature">module <span class="name-decl">deprecated.deprecated</span></div>
<div class="doc-comment"><p>A module from a deprecated package</p></div>
<dl class="member-info">
<dt class="">Module URI:</dt>
<dd><span class="import-uri">package://localhost:0/deprecated@1.0.0#/deprecated.pkl</span><i class="copy-uri-button material-icons">content_copy</i></dd>
<dt class="runtime-data hidden">Known subtypes:</dt>
<dd id="known-subtypes" class="runtime-data hidden"></dd>
<dt class="runtime-data hidden">Known usages:</dt>
<dd id="known-usages" class="runtime-data hidden"></dd>
<dt class="runtime-data hidden">All versions:</dt>
<dd id="known-versions" class="runtime-data hidden"></dd>
</dl>
</div>
<div class="member-group">
<div id="_properties" class="anchor"> </div>
<h2 class="member-group-title">Properties<span class="toggle-inherited-members">(<span class="toggle-inherited-members-link button-link">show inherited</span>)</span></h2>
<ul>
<li>
<div id="output" class="anchor"> </div>
<div class="member inherited expandable hidden collapsed with-expandable-docs"><i class="material-icons expandable-docs-icon">expand_more</i><a class="member-selflink material-icons" href="#output">link</a>
<div class="member-left">
<div class="member-modifiers">hidden </div>
</div>
<div class="member-main">
<div class="member-signature"><span class="name-decl">output</span>: <a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/ModuleOutput.html" class="name-ref">ModuleOutput</a><span class="context"> (<a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/index.html" class="name-ref">pkl.base</a>)</span><a class="member-source-link" href="https://github.com/apple/pkl/blob/0.24.0/stdlib/base.pkl#L123-L456">Source</a></div>
<div class="doc-comment"><p>The output of this module.</p></div>
<div class="doc-comment expandable hidden collapsed"><p>Defaults to all module properties rendered as either Pcf or the format specified on the command line.</p></div>
</div>
</div>
</li>
<li>
<div id="foo" class="anchor"> </div>
<div class="member with-expandable-docs"><i class="material-icons expandable-docs-icon">expand_more</i><a class="member-selflink material-icons" href="#foo">link</a>
<div class="member-left">
<div class="member-modifiers member-deprecated"></div>
</div>
<div class="member-main">
<div class="member-signature member-deprecated"><span class="name-decl">foo</span>: <a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/Int.html" class="name-ref">Int</a></div>
<div class="doc-comment">Deprecated. Replace with: <code>bar</code></div>
<div class="doc-comment expandable hidden collapsed"><p>Old foo</p></div>
</div>
</div>
</li>
<li>
<div id="bar" class="anchor"> </div>
<div class="member"><a class="member-selflink material-icons" href="#bar">link</a>
<div class="member-left">
<div class="member-modifiers"></div>
</div>
<div class="member-main">
<div class="member-signature"><span class="name-decl">bar</span>: <a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/Int.html" class="name-ref">Int</a></div>
<div class="doc-comment"><p>New bar</p></div>
</div>
</div>
</li>
</ul>
</div>
<div class="member-group">
<div id="_methods" class="anchor"> </div>
<h2 class="member-group-title">Methods<span class="toggle-inherited-members">(<span class="toggle-inherited-members-link button-link">show inherited</span>)</span></h2>
<ul>
<li>
<div id="getClass()" class="anchor"> </div>
<div class="member inherited expandable hidden collapsed"><a class="member-selflink material-icons" href="#getClass()">link</a>
<div class="member-left">
<div class="member-modifiers">function </div>
</div>
<div class="member-main">
<div class="member-signature"><span class="name-decl">getClass</span>(): <a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/Class.html" class="name-ref">Class</a><span class="context"> (<a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/index.html" class="name-ref">pkl.base</a>)</span><a class="member-source-link" href="https://github.com/apple/pkl/blob/0.24.0/stdlib/base.pkl#L123-L456">Source</a></div>
<div class="doc-comment"><p>Returns the class of <code>this</code>.</p></div>
</div>
</div>
</li>
<li>
<div id="toString()" class="anchor"> </div>
<div class="member inherited expandable hidden collapsed with-expandable-docs"><i class="material-icons expandable-docs-icon">expand_more</i><a class="member-selflink material-icons" href="#toString()">link</a>
<div class="member-left">
<div class="member-modifiers">function </div>
</div>
<div class="member-main">
<div class="member-signature"><span class="name-decl">toString</span>(): <a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/String.html" class="name-ref">String</a><span class="context"> (<a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/index.html" class="name-ref">pkl.base</a>)</span><a class="member-source-link" href="https://github.com/apple/pkl/blob/0.24.0/stdlib/base.pkl#L123-L456">Source</a></div>
<div class="doc-comment"><p>Returns a string representation of <code>this</code>.</p></div>
<div class="doc-comment expandable hidden collapsed"><p>This method is used to convert the values of string interpolation expressions to strings.</p></div>
</div>
</div>
</li>
<li>
<div id="ifNonNull()" class="anchor"> </div>
<div id="ifNonNull().Result" class="anchor-param1"> </div>
<div id="ifNonNull().transform" class="anchor-param2"> </div>
<div class="member inherited expandable hidden collapsed with-expandable-docs"><i class="material-icons expandable-docs-icon">expand_more</i><a class="member-selflink material-icons" href="#ifNonNull()">link</a>
<div class="member-left">
<div class="member-modifiers">function </div>
</div>
<div class="member-main">
<div class="member-signature"><span class="name-decl">ifNonNull</span>&lt;<a class="param1">Result</a>&gt;(<span class="param2">transform</span>: (<a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/index.html#NonNull" class="name-ref">NonNull</a>) -&gt; <a href="index.html#ifNonNull().Result" class="name-ref">Result</a>): <a href="index.html#ifNonNull().Result" class="name-ref">Result</a>?<span class="context"> (<a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/index.html" class="name-ref">pkl.base</a>)</span><a class="member-source-link" href="https://github.com/apple/pkl/blob/0.24.0/stdlib/base.pkl#L123-L456">Source</a></div>
<div class="doc-comment"><p>Returns <code>this |&gt; transform</code> if <code>this</code> is non-null, and <code>null</code> otherwise.</p></div>
<div class="doc-comment expandable hidden collapsed"><p>This method is the complement of the <code>??</code> operator and the equivalent of an <code>Option</code> type's <code>map</code> and <code>flatMap</code> methods.</p></div>
</div>
</div>
</li>
<li>
<div id="hasProperty()" class="anchor"> </div>
<div id="hasProperty().name" class="anchor-param1"> </div>
<div class="member inherited expandable hidden collapsed"><a class="member-selflink material-icons" href="#hasProperty()">link</a>
<div class="member-left">
<div class="member-modifiers">function </div>
</div>
<div class="member-main">
<div class="member-signature"><span class="name-decl">hasProperty</span>(<span class="param1">name</span>: <a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/String.html" class="name-ref">String</a>): <a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/Boolean.html" class="name-ref">Boolean</a><span class="context"> (<a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/index.html" class="name-ref">pkl.base</a>)</span><a class="member-source-link" href="https://github.com/apple/pkl/blob/0.24.0/stdlib/base.pkl#L123-L456">Source</a></div>
<div class="doc-comment"><p>Tells if this object has a property with the given <code>name</code>.</p></div>
</div>
</div>
</li>
<li>
<div id="getProperty()" class="anchor"> </div>
<div id="getProperty().name" class="anchor-param1"> </div>
<div class="member inherited expandable hidden collapsed with-expandable-docs"><i class="material-icons expandable-docs-icon">expand_more</i><a class="member-selflink material-icons" href="#getProperty()">link</a>
<div class="member-left">
<div class="member-modifiers">function </div>
</div>
<div class="member-main">
<div class="member-signature"><span class="name-decl">getProperty</span>(<span class="param1">name</span>: <a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/String.html" class="name-ref">String</a>): unknown<span class="context"> (<a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/index.html" class="name-ref">pkl.base</a>)</span><a class="member-source-link" href="https://github.com/apple/pkl/blob/0.24.0/stdlib/base.pkl#L123-L456">Source</a></div>
<div class="doc-comment"><p>Returns the value of the property with the given <code>name</code>.</p></div>
<div class="doc-comment expandable hidden collapsed"><p>Throws if a property with this name does not exist.</p></div>
</div>
</div>
</li>
<li>
<div id="getPropertyOrNull()" class="anchor"> </div>
<div id="getPropertyOrNull().name" class="anchor-param1"> </div>
<div class="member inherited expandable hidden collapsed with-expandable-docs"><i class="material-icons expandable-docs-icon">expand_more</i><a class="member-selflink material-icons" href="#getPropertyOrNull()">link</a>
<div class="member-left">
<div class="member-modifiers">function </div>
</div>
<div class="member-main">
<div class="member-signature"><span class="name-decl">getPropertyOrNull</span>(<span class="param1">name</span>: <a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/String.html" class="name-ref">String</a>): unknown?<span class="context"> (<a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/index.html" class="name-ref">pkl.base</a>)</span><a class="member-source-link" href="https://github.com/apple/pkl/blob/0.24.0/stdlib/base.pkl#L123-L456">Source</a></div>
<div class="doc-comment"><p>Returns the value of the property with the given <code>name</code>.</p></div>
<div class="doc-comment expandable hidden collapsed"><p>Returns <code>null</code> if a property with this name does not exist.</p></div>
</div>
</div>
</li>
<li>
<div id="toDynamic()" class="anchor"> </div>
<div class="member inherited expandable hidden collapsed"><a class="member-selflink material-icons" href="#toDynamic()">link</a>
<div class="member-left">
<div class="member-modifiers">function </div>
</div>
<div class="member-main">
<div class="member-signature"><span class="name-decl">toDynamic</span>(): <a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/Dynamic.html" class="name-ref">Dynamic</a><span class="context"> (<a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/index.html" class="name-ref">pkl.base</a>)</span><a class="member-source-link" href="https://github.com/apple/pkl/blob/0.24.0/stdlib/base.pkl#L123-L456">Source</a></div>
<div class="doc-comment"><p>Converts this object to a <a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/Dynamic.html"><code>Dynamic</code></a> object.</p></div>
</div>
</div>
</li>
<li>
<div id="toMap()" class="anchor"> </div>
<div class="member inherited expandable hidden collapsed"><a class="member-selflink material-icons" href="#toMap()">link</a>
<div class="member-left">
<div class="member-modifiers">function </div>
</div>
<div class="member-main">
<div class="member-signature"><span class="name-decl">toMap</span>(): <a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/Map.html" class="name-ref">Map</a>&lt;<a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/String.html" class="name-ref">String</a>, unknown&gt;<span class="context"> (<a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/index.html" class="name-ref">pkl.base</a>)</span><a class="member-source-link" href="https://github.com/apple/pkl/blob/0.24.0/stdlib/base.pkl#L123-L456">Source</a></div>
<div class="doc-comment"><p>Converts this object to a <a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/Map.html"><code>Map</code></a>.</p></div>
</div>
</div>
</li>
<li>
<div id="relativePathTo()" class="anchor"> </div>
<div id="relativePathTo().other" class="anchor-param1"> </div>
<div class="member inherited expandable hidden collapsed with-expandable-docs"><i class="material-icons expandable-docs-icon">expand_more</i><a class="member-selflink material-icons" href="#relativePathTo()">link</a>
<div class="member-left">
<div class="member-modifiers">function </div>
</div>
<div class="member-main">
<div class="member-signature"><span class="name-decl">relativePathTo</span>(<span class="param1">other</span>: <a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/Module.html" class="name-ref">Module</a>): <a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/List.html" class="name-ref">List</a>&lt;<a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/String.html" class="name-ref">String</a>&gt;<span class="context"> (<a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/index.html" class="name-ref">pkl.base</a>)</span><a class="member-source-link" href="https://github.com/apple/pkl/blob/0.24.0/stdlib/base.pkl#L123-L456">Source</a></div>
<div class="doc-comment"><p>Returns the relative, descendent directory path between this module and <code>other</code>.</p></div>
<div class="doc-comment expandable hidden collapsed"><p>Throws if no such path exists.</p>
<p>For example, if module <code>mod1</code> has path <code>/dir1/mod1.pkl</code>, and module <code>mod2</code> has path <code>/dir1/dir2/dir3/mod2.pkl</code>,
then <code>mod1.relativePathTo(mod2)</code> will return <code>List(&quot;dir2&quot;, &quot;dir3&quot;)</code>.</p>
<p>A common use case is to compute the directory path between a template located at the root of a hierarchy
(say <code>rootModule.pkl</code>) and the currently evaluated module (accessible via the <code>module</code> keyword):</p>
<pre><code>import &quot;rootModule.pkl&quot; // self-import
path = rootModule.relativePathTo(module)
</code></pre></div>
</div>
</div>
</li>
</ul>
</div>
</main>
</body>
</html>

View File

@@ -0,0 +1,68 @@
<!DOCTYPE html>
<html>
<head>
<title>localhost:0/deprecated (1.0.0) • Docsite Title</title>
<script src="../../../scripts/pkldoc.js" defer="defer"></script>
<script src="../../../scripts/scroll-into-view.min.js" defer="defer"></script>
<script src="../../../data/localhost(3a)0/deprecated/1.0.0/index.js" defer="defer"></script>
<link href="../../../styles/pkldoc.css" media="screen" type="text/css" rel="stylesheet">
<link rel="icon" type="image/svg+xml" href="../../../images/favicon.svg">
<link rel="apple-touch-icon" sizes="180x180" href="../../../images/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="../../../images/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="../../../images/favicon-16x16.png">
<meta charset="UTF-8">
</head>
<body onload="onLoad()">
<header>
<div id="doc-title"><a href="../../../index.html">Docsite Title</a></div>
<div id="search"><i id="search-icon" class="material-icons">search</i><input id="search-input" type="search" placeholder="Click or press 'S' to search this package" autocomplete="off" data-package-name="localhost:0/deprecated" data-package-version="1.0.0" data-package-url-prefix="" data-root-url-prefix="../../../"></div>
</header>
<main><a class="declaration-parent-link" href="../../../index.html">Docsite Title</a>
<h1 id="declaration-title">localhost:0/deprecated<span id="declaration-version">1.0.0</span></h1>
<ul class="member-group-links">
<li><a href="#_modules">Modules</a></li>
</ul>
<div id="_overview" class="anchor"> </div>
<div id="_declaration" class="member">
<div class="member-signature">package <span class="name-decl">localhost:0/deprecated</span></div>
<div class="doc-comment">Deprecated: don't use</div>
<dl class="member-info">
<dt class="">URI:</dt>
<dd><span class="import-uri">package://localhost:0/deprecated@1.0.0</span><i class="copy-uri-button material-icons">content_copy</i></dd>
<dt class="">Authors:</dt>
<dd>deprecated@example.com</dd>
<dt class="">Version:</dt>
<dd>1.0.0</dd>
<dt class="">Source code:</dt>
<dd><a href="https://example.com/deprecated">https://example.com/deprecated</a></dd>
<dt class="">Issue tracker:</dt>
<dd><a href="https://example.com/deprecated/issues">https://example.com/deprecated/issues</a></dd>
<dt class="">Checksum:</dt>
<dd>7589f1b802d6b5b93c468fb6399d2235d44d83f27409da2b036455ccb6e07ce5</dd>
<dt class="runtime-data hidden">Known usages:</dt>
<dd id="known-usages" class="runtime-data hidden"></dd>
<dt class="runtime-data hidden">All versions:</dt>
<dd id="known-versions" class="runtime-data hidden"></dd>
</dl>
</div>
<div class="member-group">
<div id="_modules" class="anchor"> </div>
<h2 class="member-group-title">Modules</h2>
<ul>
<li>
<div id="deprecated.deprecated" class="anchor"> </div>
<div class="member with-page-link"><a class="member-selflink material-icons" href="#deprecated.deprecated">link</a>
<div class="member-left">
<div class="member-modifiers">module </div>
</div>
<div class="member-main">
<div class="member-signature"><a class="name-decl" href="./deprecated/index.html">deprecated.deprecated</a></div>
<div class="doc-comment"><p>A module from a deprecated package</p></div>
</div>
</div>
</li>
</ul>
</div>
</main>
</body>
</html>

View File

@@ -0,0 +1 @@
{"ref":{"pkg":"localhost:0/deprecated","pkgUri":"package://localhost:0/deprecated@1.0.0","version":"1.0.0"},"deprecation":"don't use","sourceCode":"https://example.com/deprecated","sourceCodeUrlScheme":null,"dependencies":[{"ref":{"pkg":"pkl","pkgUri":null,"version":"0.24.0"}}],"modules":[{"ref":{"pkg":"localhost:0/deprecated","pkgUri":"package://localhost:0/deprecated@1.0.0","version":"1.0.0","module":"deprecated"},"summary":"A module from a deprecated package","moduleClass":{"ref":{"pkg":"localhost:0/deprecated","pkgUri":"package://localhost:0/deprecated@1.0.0","version":"1.0.0","module":"deprecated","type":"ModuleClass"},"superclasses":[{"pkg":"pkl","pkgUri":null,"version":"0.24.0","module":"base","type":"Module"},{"pkg":"pkl","pkgUri":null,"version":"0.24.0","module":"base","type":"Typed"},{"pkg":"pkl","pkgUri":null,"version":"0.24.0","module":"base","type":"Object"},{"pkg":"pkl","pkgUri":null,"version":"0.24.0","module":"base","type":"Any"}]}}]}

View File

@@ -0,0 +1 @@
searchData='[{"name":"deprecated.deprecated","kind":1,"url":"deprecated/index.html"},{"name":"foo","kind":5,"url":"deprecated/index.html#foo","sig":": Int","parId":0,"deprecated":true},{"name":"bar","kind":5,"url":"deprecated/index.html#bar","sig":": Int","parId":0}]';

View File

@@ -0,0 +1 @@
1.0.0

File diff suppressed because one or more lines are too long

View File

@@ -123,7 +123,9 @@ class CliDocGeneratorTest {
package1PackageModule,
package2PackageModule,
URI("package://localhost:0/birds@0.5.0"),
URI("package://localhost:0/fruit@1.1.0")
URI("package://localhost:0/fruit@1.1.0"),
URI("package://localhost:0/unlisted@1.0.0"),
URI("package://localhost:0/deprecated@1.0.0"),
) + package1InputModules + package2InputModules,
moduleCacheDir = cacheDir
),