Skip to content

Commit f6b6e50

Browse files
BarkingBadBarkingBad
authored
Scaladoc features parity with old scaladoc/docs.scala-lang (#13954)
* POC * Walk in order and collect previous/next * Add `Edit on Github` button and `Contriubuted` sections * Polish gathering the contributors. CSSes fixes. * Fix tooltipping snippets * Fix handling relative links for static site * Add redirects mechanism for scaladoc * Fix leftover * Fix tests * Fix gathering index html for sections without explicit index * Apply requested changes to scaladoc * Decouple Scala.js jses. Move contributors to be independent asset/ * Add support for multiple redirects * Apply requested changes. Add static site for testcases. Fix minor bugs in scaladoc. * Fix tests
1 parent 51828cc commit f6b6e50

File tree

65 files changed

+718
-177
lines changed

Some content is hidden

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

65 files changed

+718
-177
lines changed

‎.github/workflows/scaladoc.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ jobs:
3636
java-version: 11
3737

3838
- name: Compile and test scala3doc-js
39-
run: ./project/scripts/sbt scaladoc-js/test
39+
run: ./project/scripts/sbt scaladoc-js-main/test
4040

4141
- name: Compile and test
4242
run: |

‎build.sbt

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,10 @@ val `tasty-core-bootstrapped` = Build.`tasty-core-bootstrapped`
2020
val `tasty-core-scala2` = Build.`tasty-core-scala2`
2121
val scaladoc = Build.scaladoc
2222
val `scaladoc-testcases` = Build.`scaladoc-testcases`
23-
val `scaladoc-js` = Build.`scaladoc-js`
23+
val `scaladoc-js-common` = Build.`scaladoc-js-common`
24+
val `scaladoc-js-main` = Build.`scaladoc-js-main`
25+
val `scaladoc-js-markdown` = Build.`scaladoc-js-markdown`
26+
val `scaladoc-js-contributors` = Build.`scaladoc-js-contributors`
2427
val `scala3-bench-run` = Build.`scala3-bench-run`
2528
val dist = Build.dist
2629
val `community-build` = Build.`community-build`

‎docs/_layouts/blog-page.html

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
2-
layout: main
2+
layout: static-site-main
33
---
4-
<main class="container">
4+
<main>
55
<header>
66
<h1>{{ page.title }}</h1>
77
<div class="byline">

‎docs/_layouts/doc-page.html

Lines changed: 19 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,22 @@
11
---
2-
layout: main
2+
layout: static-site-main
33
---
4-
<main class="container">
5-
<header>
6-
<h1>{{ page.title }}</h1>
7-
</header>
8-
{{ content }}
4+
<main>
5+
<header>
6+
<h1>{{ page.title }}</h1>
7+
{% if urls.editSource %}
8+
<div class="byline">
9+
<a href="{{ urls.editSource }}">
10+
<i class="far fa-edit"></i>
11+
Edit this page on GitHub
12+
</a>
13+
</div>
14+
{% endif %}
15+
</header>
16+
{{ content }}
17+
<div class="content-contributors hidden">
18+
<h5>Contributors to this page:</h5>
19+
<div id="documentation-contributors" class="contributors-container"></div>
20+
</div>
921
</main>
22+

‎docs/_layouts/main.html

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,12 @@
11
---
22
layout: base
3+
extraJS:
4+
- js/contributors.js
5+
extraCSS:
6+
- css/content-contributors.css
37
---
48
<div id="content-wrapper">
5-
{% if page.movedTo %}
6-
<aside class="warning">
7-
The content of this page is outdated. Click <a href="{{ page.movedTo }}">here</a> to find the up to date version of this page.
8-
</aside>
9-
{% endif %}
10-
{{ content }}
9+
{{ content }}
1110
</div>
1211
<script>
1312
((window.gitter = {}).chat = {}).options = {

‎docs/_layouts/redirect.html

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
hasFrame: false
3+
---
4+
<!DOCTYPE html>
5+
<html lang="en-US">
6+
<meta charset="utf-8">
7+
<title>Redirecting&hellip;</title>
8+
<link rel="canonical" href="{{ redirectTo }}">
9+
<script>location="{{ redirectTo }}"</script>
10+
<meta http-equiv="refresh" content="0; url={{ redirectTo }}">
11+
<meta name="robots" content="noindex">
12+
<h1>Redirecting&hellip;</h1>
13+
<a href="{{ redirectTo }}">Click here if you were not redirected.</a>
14+
</html>

‎docs/_layouts/static-site-main.html

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
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+
{% if page.movedTo %}
32+
<aside class="warning">
33+
The content of this page is outdated. Click <a href="{{ page.movedTo }}">here</a> to find the up to date version of this page.
34+
</aside>
35+
{% endif %}
36+
{{ content }}
37+
<nav class="arrows-wrapper" aria-label="Page navigation">
38+
{% if page.previous %}
39+
<a rel="prev" href="{{ page.previous }}" class="arrows previous" aria-keyshortcuts="Left">
40+
<i class="fa fa-angle-left"></i>
41+
</a>
42+
{% endif %}
43+
{% if page.next %}
44+
<a rel="next" href="{{ page.next }}" class="arrows next" aria-keyshortcuts="Right">
45+
<i class="fa fa-angle-right"></i>
46+
</a>
47+
{% endif %}
48+
</nav>
49+
</div>

‎docs/blog/index.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
layout: main
2+
layout: static-site-main
33
title: Blog
44
---
55
<main class="container">

‎docs/css/dottydoc.css

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,10 @@ main > h1 {
2525
margin-bottom: 20px;
2626
}
2727

28+
.byline {
29+
font-size: 14px;
30+
}
31+
2832
.byline, .byline a {
2933
color: grey;
3034
}
@@ -265,4 +269,4 @@ aside.success {
265269
header {
266270
position: static !important;
267271
width: 100% !important;
268-
}
272+
}

‎docs/docs/reference/experimental/named-typeargs.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
layout: singlepage-overview
33
scala3: true
44
title: "Named Type Arguments"
5+
redirectFrom: reference/other-new-features/named-typeargs.html
56
---
67

78
**Note:** This feature is implemented in Scala 3, but is not expected to be part of Scala 3.0.

‎docs/docs/reference/other-new-features/named-typeargs.md

Lines changed: 0 additions & 7 deletions
This file was deleted.

‎project/Build.scala

Lines changed: 45 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -340,7 +340,8 @@ object Build {
340340
"-skip-by-id:scala.runtime.MatchCase",
341341
"-project-footer", s"Copyright (c) 2002-$currentYear, LAMP/EPFL",
342342
"-author",
343-
"-groups"
343+
"-groups",
344+
"-default-template", "static-site-main"
344345
) ++ extMap
345346
}
346347

@@ -1255,16 +1256,43 @@ object Build {
12551256
lazy val `scaladoc-testcases` = project.in(file("scaladoc-testcases")).
12561257
dependsOn(`scala3-compiler-bootstrapped`).
12571258
settings(commonBootstrappedSettings)
1258-
lazy val `scaladoc-js` = project.in(file("scaladoc-js")).
1259+
1260+
1261+
/**
1262+
* Collection of projects building targets for scaladoc, these are:
1263+
* - common - common module for javascript shared among html and markdown outpu
1264+
* - main - main target for default scaladoc producing html webpage
1265+
* - markdown - companion js for preprocessing features. Can be later used with some templating engine
1266+
* - contributors - not related project to any of forementioned modules. Used for presenting contributors for static site.
1267+
* Made as an indepented project to be scaladoc-agnostic.
1268+
*/
1269+
lazy val `scaladoc-js-common` = project.in(file("scaladoc-js/common")).
1270+
enablePlugins(DottyJSPlugin).
1271+
dependsOn(`scala3-library-bootstrappedJS`).
1272+
settings(libraryDependencies += ("org.scala-js" %%% "scalajs-dom" % "1.1.0").cross(CrossVersion.for3Use2_13))
1273+
1274+
lazy val `scaladoc-js-main` = project.in(file("scaladoc-js/main")).
1275+
enablePlugins(DottyJSPlugin).
1276+
dependsOn(`scaladoc-js-common`).
1277+
settings(
1278+
scalaJSUseMainModuleInitializer := true,
1279+
Test / fork := false
1280+
)
1281+
1282+
lazy val `scaladoc-js-markdown` = project.in(file("scaladoc-js/markdown")).
1283+
enablePlugins(DottyJSPlugin).
1284+
dependsOn(`scaladoc-js-common`).
1285+
settings(
1286+
scalaJSUseMainModuleInitializer := true,
1287+
Test / fork := false
1288+
)
1289+
1290+
lazy val `scaladoc-js-contributors` = project.in(file("scaladoc-js/contributors")).
12591291
enablePlugins(DottyJSPlugin).
12601292
dependsOn(`scala3-library-bootstrappedJS`).
12611293
settings(
1262-
Compile / scalaJSMainModuleInitializer := (sys.env.get("scaladoc.projectFormat") match {
1263-
case Some("md") => Some(ModuleInitializer.mainMethod("dotty.tools.scaladoc.Main", "markdownMain"))
1264-
case _ => Some(ModuleInitializer.mainMethod("dotty.tools.scaladoc.Main", "main"))
1265-
}),
12661294
Test / fork := false,
1267-
Compile / scalaJSUseMainModuleInitializer := true,
1295+
scalaJSUseMainModuleInitializer := true,
12681296
libraryDependencies += ("org.scala-js" %%% "scalajs-dom" % "1.1.0").cross(CrossVersion.for3Use2_13)
12691297
)
12701298

@@ -1294,6 +1322,7 @@ object Build {
12941322
name,
12951323
scalaSrcLink(stdLibVersion, srcManaged(dottyNonBootstrappedVersion, "scala") + "="),
12961324
dottySrcLink(referenceVersion, srcManaged(dottyNonBootstrappedVersion, "dotty") + "=", "#library/src"),
1325+
dottySrcLink(referenceVersion, "docs-for-dotty-page=", "#docs"),
12971326
dottySrcLink(referenceVersion),
12981327
"-Ygenerate-inkuire",
12991328
) ++ scalacOptionsDocSettings(includeExternalMappings) ++ revision ++ params ++ targets
@@ -1318,54 +1347,13 @@ object Build {
13181347
).
13191348
settings(
13201349
Compile / resourceGenerators += Def.task {
1321-
val jsDestinationFile = (Compile / resourceManaged).value / "dotty_res" / "scripts" / "scaladoc-scalajs.js"
1322-
sbt.IO.copyFile((`scaladoc-js` / Compile / fullOptJS).value.data, jsDestinationFile)
1323-
Seq(jsDestinationFile)
1324-
}.taskValue,
1325-
Compile / resourceGenerators += Def.task {
1326-
Seq("code-snippets.css", "searchbar.css", "social-links.css", "ux.css", "versions-dropdown.css").map { file =>
1327-
val cssDesitnationFile = (Compile / resourceManaged).value / "dotty_res" / "styles" / file
1328-
val cssSourceFile = (`scaladoc-js` / Compile / resourceDirectory).value / file
1329-
sbt.IO.copyFile(cssSourceFile, cssDesitnationFile)
1330-
cssDesitnationFile
1331-
}
1332-
}.taskValue,
1333-
Compile / resourceGenerators += Def.task {
1334-
import _root_.scala.sys.process._
1335-
import _root_.scala.concurrent._
1336-
import _root_.scala.concurrent.duration.Duration
1337-
import ExecutionContext.Implicits.global
1338-
val inkuireVersion = "1.0.0-M3"
1339-
val inkuireLink = s"https://github.com/VirtusLab/Inkuire/releases/download/$inkuireVersion/inkuire.js"
1340-
val inkuireDestinationFile = (Compile / resourceManaged).value / "dotty_res" / "scripts" / "inkuire.js"
1341-
sbt.IO.touch(inkuireDestinationFile)
1342-
1343-
def tryFetch(retries: Int, timeout: Duration): Unit = {
1344-
val downloadProcess = (new java.net.URL(inkuireLink) #> inkuireDestinationFile).run()
1345-
val result: Future[Int] = Future(blocking(downloadProcess.exitValue()))
1346-
try {
1347-
Await.result(result, timeout) match {
1348-
case 0 =>
1349-
case res if retries > 0 =>
1350-
println(s"Failed to fetch inkuire.js from $inkuireLink: Error code $res. $retries retries left")
1351-
tryFetch(retries - 1, timeout)
1352-
case res => throw new MessageOnlyException(s"Failed to fetch inkuire.js from $inkuireLink: Error code $res")
1353-
}
1354-
} catch {
1355-
case e: TimeoutException =>
1356-
downloadProcess.destroy()
1357-
if (retries > 0) {
1358-
println(s"Failed to fetch inkuire.js from $inkuireLink: Download timeout. $retries retries left")
1359-
tryFetch(retries - 1, timeout)
1360-
}
1361-
else {
1362-
throw new MessageOnlyException(s"Failed to fetch inkuire.js from $inkuireLink: Download timeout")
1363-
}
1364-
}
1365-
}
1366-
1367-
tryFetch(5, Duration(60, "s"))
1368-
Seq(inkuireDestinationFile)
1350+
DocumentationWebsite.generateStaticAssets(
1351+
(`scaladoc-js-contributors` / Compile / fullOptJS).value.data,
1352+
(`scaladoc-js-main` / Compile / fullOptJS).value.data,
1353+
(`scaladoc-js-contributors` / Compile / baseDirectory).value / "css",
1354+
(`scaladoc-js-common` / Compile / baseDirectory).value / "css",
1355+
(Compile / resourceManaged).value,
1356+
)
13691357
}.taskValue,
13701358
libraryDependencies ++= Dependencies.flexmarkDeps ++ Seq(
13711359
"nl.big-o" % "liqp" % "0.6.8",
@@ -1456,10 +1444,10 @@ object Build {
14561444
case _ => throw new IllegalArgumentException("No js destination provided")
14571445
}
14581446
val jsDestinationFile: File = Paths.get(destJS).toFile
1459-
sbt.IO.copyFile((`scaladoc-js` / Compile / fullOptJS).value.data, jsDestinationFile)
1447+
sbt.IO.copyFile((`scaladoc-js-markdown` / Compile / fullOptJS).value.data, jsDestinationFile)
14601448
csses.map { file =>
14611449
val cssDesitnationFile = Paths.get(destCSS).toFile / file
1462-
val cssSourceFile = (`scaladoc-js` / Compile / resourceDirectory).value / file
1450+
val cssSourceFile = (`scaladoc-js-markdown` / Compile / resourceDirectory).value / file
14631451
sbt.IO.copyFile(cssSourceFile, cssDesitnationFile)
14641452
cssDesitnationFile
14651453
}

0 commit comments

Comments
 (0)