Skip to content

Commit e92666b

Browse files
pikinier20pikinier20
committed
Add task generating Scala 3 language reference
1 parent ead669e commit e92666b

File tree

5 files changed

+221
-11
lines changed

5 files changed

+221
-11
lines changed

‎project/Build.scala‎

Lines changed: 34 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1256,6 +1256,8 @@ object Build {
12561256
val generateScalaDocumentation = inputKey[Unit]("Generate documentation for dotty lib")
12571257
val generateTestcasesDocumentation = taskKey[Unit]("Generate documentation for testcases, usefull for debugging tests")
12581258

1259+
val generateReferenceDocumentation = taskKey[Unit]("Generate language reference documentation for Scala 3")
1260+
12591261
lazy val `scaladoc-testcases` = project.in(file("scaladoc-testcases")).
12601262
dependsOn(`scala3-compiler-bootstrapped`).
12611263
settings(commonBootstrappedSettings)
@@ -1378,6 +1380,31 @@ object Build {
13781380
generateDocumentation(Testcases)
13791381
}.value,
13801382

1383+
generateReferenceDocumentation := Def.taskDyn {
1384+
val temp = IO.createTemporaryDirectory
1385+
IO.copyDirectory(file("docs"), temp / "docs")
1386+
IO.delete(temp / "docs" / "_blog")
1387+
1388+
IO.copyDirectory(
1389+
file("project") / "resources" / "referenceReplacements",
1390+
temp / "docs",
1391+
overwrite = true
1392+
)
1393+
1394+
val languageReferenceConfig = Def.task {
1395+
Scala3.value
1396+
.add(OutputDir("scaladoc/output/reference"))
1397+
.add(SiteRoot(s"${temp.getAbsolutePath}/docs"))
1398+
.add(ProjectName("Scala 3 Reference"))
1399+
.add(SourceLinks(List(
1400+
dottySrcLink(referenceVersion, temp.getAbsolutePath + "=")
1401+
)))
1402+
.withTargets(List("___fake___.scala"))
1403+
}
1404+
1405+
generateDocumentation(languageReferenceConfig)
1406+
}.value,
1407+
13811408
Test / buildInfoKeys := Seq[BuildInfoKey](
13821409
(Test / Build.testcasesOutputDir),
13831410
(Test / Build.testcasesSourceRoot),
@@ -1763,6 +1790,13 @@ object ScaladocConfigs {
17631790

17641791
def dottyExternalMapping = ".*scala/.*::scaladoc3::https://dotty.epfl.ch/api/"
17651792
def javaExternalMapping = ".*java/.*::javadoc::https://docs.oracle.com/javase/8/docs/api/"
1793+
def scalaSrcLink(v: String, s: String) = s"${s}github://scala/scala/v$v#src/library"
1794+
def dottySrcLink(v: String, sourcesPrefix: String = "", outputPrefix: String = "") =
1795+
sys.env.get("GITHUB_SHA") match {
1796+
case Some(sha) =>
1797+
s"${sourcesPrefix}github://${sys.env("GITHUB_REPOSITORY")}/$sha$outputPrefix"
1798+
case None => s"${sourcesPrefix}github://lampepfl/dotty/$v$outputPrefix"
1799+
}
17661800

17671801
lazy val DefaultGenerationConfig = Def.task {
17681802
def distLocation = (dist / pack).value
@@ -1771,13 +1805,6 @@ object ScaladocConfigs {
17711805
def scalaLib = findArtifactPath(externalCompilerClasspathTask.value, "scala-library")
17721806
def dottyLib = (`scala3-library` / Compile / classDirectory).value
17731807
def srcManaged(v: String, s: String) = s"out/bootstrap/stdlib-bootstrapped/scala-$v/src_managed/main/$s-library-src"
1774-
def scalaSrcLink(v: String, s: String) = s"${s}github://scala/scala/v$v#src/library"
1775-
def dottySrcLink(v: String, sourcesPrefix: String = "", outputPrefix: String = "") =
1776-
sys.env.get("GITHUB_SHA") match {
1777-
case Some(sha) =>
1778-
s"${sourcesPrefix}github://${sys.env("GITHUB_REPOSITORY")}/$sha$outputPrefix"
1779-
case None => s"${sourcesPrefix}github://lampepfl/dotty/$v$outputPrefix"
1780-
}
17811808

17821809
def defaultSourceLinks: SourceLinks = SourceLinks(
17831810
List(

‎project/resources/referenceReplacements/_layouts/static-site-main.html‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
layout: main
3+
---
4+
<div class="container">
5+
<div id="site-header">
6+
<div class="wrap">
7+
<nav class="navigation" role="menu">
8+
<ul class="navigation-menu">
9+
<li class="navigation-menu-item">
10+
<a href="https://docs.scala-lang.org/" class="active">Documentation</a>
11+
</li>
12+
<li class="navigation-menu-item">
13+
<a href="https://www.scala-lang.org/download/">Download</a>
14+
</li>
15+
<li class="navigation-menu-item">
16+
<a href="https://www.scala-lang.org/community/">Community</a>
17+
</li>
18+
<li class="navigation-menu-item">
19+
<a href="https://index.scala-lang.org">Libraries</a>
20+
</li>
21+
<li class="navigation-menu-item">
22+
<a href="https://www.scala-lang.org/contribute/">Contribute</a>
23+
</li>
24+
<li class="navigation-menu-item">
25+
<a href="https://www.scala-lang.org/blog/">Blog</a>
26+
</li>
27+
</ul>
28+
</nav>
29+
</div>
30+
</div>
31+
{{ content }}
32+
<nav class="arrows-wrapper" aria-label="Page navigation">
33+
{% if page.previous %}
34+
<a rel="prev" href="{{ page.previous }}" class="arrows previous" aria-keyshortcuts="Left">
35+
<i class="fa fa-angle-left"></i>
36+
</a>
37+
{% endif %}
38+
{% if page.next %}
39+
<a rel="next" href="{{ page.next }}" class="arrows next" aria-keyshortcuts="Right">
40+
<i class="fa fa-angle-right"></i>
41+
</a>
42+
{% endif %}
43+
</nav>
44+
</div>

‎project/resources/referenceReplacements/sidebar.yml‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
index: reference/overview.md
2+
subsection:
3+
- page: reference/overview.md
4+
- title: New Types
5+
index: reference/new-types/new-types.md
6+
subsection:
7+
- page: reference/new-types/intersection-types.md
8+
- page: reference/new-types/intersection-types-spec.md
9+
- page: reference/new-types/union-types.md
10+
- page: reference/new-types/union-types-spec.md
11+
- page: reference/new-types/type-lambdas.md
12+
- page: reference/new-types/type-lambdas-spec.md
13+
- page: reference/new-types/match-types.md
14+
- page: reference/new-types/dependent-function-types.md
15+
- page: reference/new-types/dependent-function-types-spec.md
16+
- page: reference/new-types/polymorphic-function-types.md
17+
- title: Enums
18+
index: reference/enums/enums-index.md
19+
subsection:
20+
- page: reference/enums/enums.md
21+
- page: reference/enums/adts.md
22+
- page: reference/enums/desugarEnums.md
23+
- title: Contextual Abstractions
24+
index: reference/contextual/contextual.md
25+
directory: contextual
26+
subsection:
27+
- page: reference/contextual/givens.md
28+
- page: reference/contextual/using-clauses.md
29+
- page: reference/contextual/context-bounds.md
30+
- page: reference/contextual/given-imports.md
31+
- page: reference/contextual/extension-methods.md
32+
- page: reference/contextual/right-associative-extension-methods.md
33+
- page: reference/contextual/type-classes.md
34+
- page: reference/contextual/derivation.md
35+
- page: reference/contextual/derivation-macro.md
36+
- page: reference/contextual/multiversal-equality.md
37+
- page: reference/contextual/context-functions.md
38+
- page: reference/contextual/context-functions-spec.md
39+
- page: reference/contextual/conversions.md
40+
- page: reference/contextual/by-name-context-parameters.md
41+
- page: reference/contextual/relationship-implicits.md
42+
- title: Metaprogramming
43+
index: reference/metaprogramming/metaprogramming.md
44+
subsection:
45+
- page: reference/metaprogramming/inline.md
46+
- page: reference/metaprogramming/compiletime-ops.md
47+
- page: reference/metaprogramming/macros.md
48+
- page: reference/metaprogramming/macros-spec.md
49+
- page: reference/metaprogramming/staging.md
50+
- page: reference/metaprogramming/reflection.md
51+
- page: reference/metaprogramming/tasty-inspect.md
52+
- title: Other New Features
53+
index: reference/other-new-features/other-new-types.md
54+
subsection:
55+
- page: reference/other-new-features/trait-parameters.md
56+
- page: reference/other-new-features/transparent-traits.md
57+
- page: reference/other-new-features/creator-applications.md
58+
- page: reference/other-new-features/export.md
59+
- page: reference/other-new-features/opaques.md
60+
- page: reference/other-new-features/opaques-details.md
61+
- page: reference/other-new-features/open-classes.md
62+
- page: reference/other-new-features/parameter-untupling.md
63+
- page: reference/other-new-features/parameter-untupling-spec.md
64+
- page: reference/other-new-features/kind-polymorphism.md
65+
- page: reference/other-new-features/matchable.md
66+
- page: reference/other-new-features/threadUnsafe-annotation.md
67+
- page: reference/other-new-features/targetName.md
68+
- page: reference/other-new-features/control-syntax.md
69+
- page: reference/other-new-features/indentation.md
70+
- page: reference/other-new-features/safe-initialization.md
71+
- page: reference/other-new-features/type-test.md
72+
- page: reference/other-new-features/experimental-defs.md
73+
- title: Other Changed Features
74+
directory: changed-features
75+
index: reference/changed-features/changed-features.md
76+
subsection:
77+
- page: reference/changed-features/numeric-literals.md
78+
- page: reference/changed-features/structural-types.md
79+
- page: reference/changed-features/structural-types-spec.md
80+
- page: reference/changed-features/operators.md
81+
- page: reference/changed-features/wildcards.md
82+
- page: reference/changed-features/imports.md
83+
- page: reference/changed-features/type-checking.md
84+
- page: reference/changed-features/type-inference.md
85+
- page: reference/changed-features/implicit-resolution.md
86+
- page: reference/changed-features/implicit-conversions.md
87+
- page: reference/changed-features/implicit-conversions-spec.md
88+
- page: reference/changed-features/overload-resolution.md
89+
- page: reference/changed-features/match-syntax.md
90+
- page: reference/changed-features/vararg-splices.md
91+
- page: reference/changed-features/pattern-bindings.md
92+
- page: reference/changed-features/pattern-matching.md
93+
- page: reference/changed-features/eta-expansion.md
94+
- page: reference/changed-features/eta-expansion-spec.md
95+
- page: reference/changed-features/compiler-plugins.md
96+
- page: reference/changed-features/lazy-vals-init.md
97+
- page: reference/changed-features/main-functions.md
98+
- title: Dropped Features
99+
index: reference/dropped-features/dropped-features.md
100+
subsection:
101+
- page: reference/dropped-features/delayed-init.md
102+
- page: reference/dropped-features/macros.md
103+
- page: reference/dropped-features/existential-types.md
104+
- page: reference/dropped-features/type-projection.md
105+
- page: reference/dropped-features/do-while.md
106+
- page: reference/dropped-features/procedure-syntax.md
107+
- page: reference/dropped-features/package-objects.md
108+
- page: reference/dropped-features/early-initializers.md
109+
- page: reference/dropped-features/class-shadowing.md
110+
- page: reference/dropped-features/class-shadowing-spec.md
111+
- page: reference/dropped-features/limit22.md
112+
- page: reference/dropped-features/xml.md
113+
- page: reference/dropped-features/symlits.md
114+
- page: reference/dropped-features/auto-apply.md
115+
- page: reference/dropped-features/weak-conformance.md
116+
- page: reference/dropped-features/weak-conformance-spec.md
117+
- page: reference/dropped-features/nonlocal-returns.md
118+
- page: reference/dropped-features/this-qualifier.md
119+
- page: reference/dropped-features/wildcard-init.md
120+
- title: Experimental Features
121+
directory: experimental
122+
subsection:
123+
- page: reference/experimental/overview.md
124+
- page: reference/experimental/canthrow.md
125+
- page: reference/experimental/erased-defs.md
126+
- page: reference/experimental/erased-defs-spec.md
127+
- page: reference/experimental/named-typeargs.md
128+
- page: reference/experimental/named-typeargs-spec.md
129+
- page: reference/experimental/numeric-literals.md
130+
- page: reference/experimental/explicit-nulls.md
131+
- page: reference/experimental/cc.md
132+
- page: reference/syntax.md
133+
- title: Language Versions
134+
index: reference/language-versions/language-versions.md
135+
subsection:
136+
- page: reference/language-versions/source-compatibility.md
137+
- page: reference/language-versions/binary-compatibility.md
138+
- page: reference/soft-modifier.md
139+
- page: reference/features-classification.md

‎scaladoc/src/dotty/tools/scaladoc/PathBased.scala‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,7 @@ import java.nio.file.{Path, Paths}
44

55
case class PathBased[T](entries: List[PathBased.Entry[T]], projectRoot: Path):
66
def get(path: Path): Option[PathBased.Result[T]] =
7-
if path.isAbsolute then
8-
if path.startsWith(projectRoot) then get(projectRoot.relativize(path))
9-
else None
7+
if path.isAbsolute && path.startsWith(projectRoot) then get(projectRoot.relativize(path))
108
else entries.filter(_.path.forall(p => path.startsWith(p))).maxByOption(_.path.map(_.toString.length)).map(entry =>
119
PathBased.Result(entry.path.fold(path)(_.relativize(path)), entry.elem)
1210
)

‎scaladoc/src/dotty/tools/scaladoc/renderers/Renderer.scala‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,9 @@ abstract class Renderer(rootPackage: Member, val members: Map[DRI, Member], prot
8383
then rootPckPage.withTitle(args.name)
8484
else {
8585
val newRootPage = templateToPage(newRoot, siteContext)
86-
newRootPage.withNewChildren(Seq(rootPckPage.withTitle("API")))
86+
newRootPage.withNewChildren(
87+
Seq(rootPckPage.withTitle("API")).filter(_ => rootPackage.members.nonEmpty)
88+
)
8789
}
8890

8991
val redirectPages: Seq[Page] = staticSite.fold(Seq.empty)(siteContext => siteContext.redirectTemplates.map {

0 commit comments

Comments
 (0)