Skip to content

Commit f4260b5

Browse files
romanowskiromanowski
authored
Merge pull request #13130 from romanowski/scaladoc/api-layout
Scaladoc generate flatten structure for API rather then put everything in `api` directory
2 parents 372930e + 49f2d03 commit f4260b5

File tree

21 files changed

+161
-74
lines changed

21 files changed

+161
-74
lines changed

‎project/Build.scala‎

Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1325,6 +1325,7 @@ object Build {
13251325
generateScalaDocumentation := Def.inputTaskDyn {
13261326
val extraArgs = spaceDelimited("[output]").parsed
13271327
val dest = file(extraArgs.headOption.getOrElse("scaladoc/output/scala3")).getAbsoluteFile
1328+
val justAPI = extraArgs.drop(1).headOption == Some("--justAPI")
13281329
val majorVersion = (LocalProject("scala3-library-bootstrapped") / scalaBinaryVersion).value
13291330

13301331
val dottyJars: Seq[java.io.File] = Seq(
@@ -1346,21 +1347,24 @@ object Build {
13461347

13471348
val dottyLibRoot = projectRoot.relativize(dottyManagesSources.toPath.normalize())
13481349

1350+
def generateDocTask =
1351+
generateDocumentation(
1352+
roots, "Scala 3", dest.getAbsolutePath, "master",
1353+
Seq(
1354+
"-comment-syntax", "wiki",
1355+
s"-source-links:docs=github://lampepfl/dotty/master#docs",
1356+
"-doc-root-content", docRootFile.toString,
1357+
"-Ydocument-synthetic-types"
1358+
) ++ (if (justAPI) Nil else Seq("-siteroot", "docs", "-Yapi-subdirectory")))
1359+
13491360
if (dottyJars.isEmpty) Def.task { streams.value.log.error("Dotty lib wasn't found") }
1361+
else if (justAPI) generateDocTask
13501362
else Def.task{
13511363
IO.write(dest / "versions" / "latest-nightly-base", majorVersion)
13521364

13531365
// This file is used by GitHub Pages when the page is available in a custom domain
13541366
IO.write(dest / "CNAME", "dotty.epfl.ch")
1355-
}.dependsOn(generateDocumentation(
1356-
roots, "Scala 3", dest.getAbsolutePath, "master",
1357-
Seq(
1358-
"-comment-syntax", "wiki",
1359-
"-siteroot", "docs",
1360-
s"-source-links:docs=github://lampepfl/dotty/master#docs",
1361-
"-doc-root-content", docRootFile.toString,
1362-
"-Ydocument-synthetic-types"
1363-
)))
1367+
}.dependsOn(generateDocTask)
13641368
}.evaluated,
13651369

13661370
generateTestcasesDocumentation := Def.taskDyn {

‎sbt-test/sbt-dotty/scaladoc/build.sbt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,6 @@ TaskKey[Unit]("checkScaladocOptions") := {
66
}
77

88
TaskKey[Unit]("checkHtmlFiles") := {
9-
val helloHtml = (Compile / doc / target).value / "api" / "hello.html"
9+
val helloHtml = (Compile / doc / target).value / "hello.html"
1010
assert(helloHtml.exists)
1111
}

‎scaladoc-testcases/src/docs/tests/Adoc.scala‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
package docs.tests
2+
3+
class Adoc:
4+
def foo = 123

‎scaladoc-testcases/src/resources/tests/Adoc.scala‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
package resources.tests
2+
3+
class Adoc:
4+
def foo = 123

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

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,8 @@ object Scaladoc:
5858
snippetCompilerDebug: Boolean = false,
5959
noLinkWarnings: Boolean = false,
6060
versionsDictionaryUrl: Option[String] = None,
61-
generateInkuire : Boolean = false
61+
generateInkuire : Boolean = false,
62+
apiSubdirectory : Boolean = false
6263
)
6364

6465
def run(args: Array[String], rootContext: CompilerContext): Reporter =
@@ -223,7 +224,8 @@ object Scaladoc:
223224
noLinkWarnings.get,
224225
snippetCompilerDebug.get,
225226
versionsDictionaryUrl.nonDefault,
226-
generateInkuire.get
227+
generateInkuire.get,
228+
apiSubdirectory.get,
227229
)
228230
(Some(docArgs), newContext)
229231
}

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -120,5 +120,8 @@ class ScaladocSettings extends SettingGroup with AllScalaSettings:
120120
val generateInkuire: Setting[Boolean] =
121121
BooleanSetting("-Ygenerate-inkuire", "Generates InkuireDB and enables Hoogle-like searches", false)
122122

123+
val apiSubdirectory: Setting[Boolean] =
124+
BooleanSetting("-Yapi-subdirectory", "Keep all api member inside `api` directory", false)
125+
123126
def scaladocSpecificSettings: Set[Setting[_]] =
124127
Set(sourceLinks, syntax, revision, externalDocumentationMappings, socialLinks, skipById, skipByRegex, deprecatedSkipPackages, docRootContent, snippetCompiler, snippetCompilerDebug, generateInkuire)

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

Lines changed: 23 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -64,13 +64,18 @@ class HtmlRenderer(rootPackage: Member, val members: Map[DRI, Member])(using ctx
6464
children = Nil
6565
))
6666
case Some(siteContext) =>
67-
(siteContext.orphanedTemplates :+ siteContext.indexTemplate()).map(templateToPage(_, siteContext))
67+
// In case that we do not have an index page and we do not have any API entries
68+
// we want to create empty index page, so there is one
69+
val actualIndexTemplate = siteContext.indexTemplates() match
70+
case Nil if effectiveMembers.isEmpty => Seq(siteContext.emptyIndexTemplate)
71+
case templates => templates
72+
73+
(siteContext.orphanedTemplates ++ actualIndexTemplate).map(templateToPage(_, siteContext))
6874

6975
/**
7076
* Here we have to retrive index pages from hidden pages and replace fake index pages in navigable page tree.
7177
*/
72-
private def getAllPages: Seq[Page] =
73-
78+
val allPages: Seq[Page] =
7479
def traversePages(page: Page): (Page, Seq[Page]) =
7580
val (newChildren, newPagesToRemove): (Seq[Page], Seq[Page]) = page.children.map(traversePages(_)).foldLeft((Seq[Page](), Seq[Page]())) {
7681
case ((pAcc, ptrAcc), (p, ptr)) => (pAcc :+ p, ptrAcc ++ ptr)
@@ -83,9 +88,22 @@ class HtmlRenderer(rootPackage: Member, val members: Map[DRI, Member])(using ctx
8388

8489
val (newNavigablePage, pagesToRemove) = traversePages(navigablePage)
8590

86-
newNavigablePage +: hiddenPages.filterNot(pagesToRemove.contains)
91+
val all = newNavigablePage +: hiddenPages.filterNot(pagesToRemove.contains)
92+
// We need to check for conflicts only if we have top-level member called blog or docs
93+
val hasPotentialConflict =
94+
rootPackage.members.exists(m => m.name.startsWith("docs") || m.name.startsWith("blog"))
95+
96+
if hasPotentialConflict then
97+
def walk(page: Page): Unit =
98+
if page.link.dri.isStaticFile then
99+
val dest = absolutePath(page.link.dri)
100+
if apiPaths.contains(dest) then
101+
report.error(s"Conflict between static page and API member for $dest. $pathsConflictResoultionMsg")
102+
page.children.foreach(walk)
103+
104+
all.foreach (walk)
87105

88-
val allPages = getAllPages
106+
all
89107

90108
def renderContent(page: Page) = page.content match
91109
case m: Member =>

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

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,15 +19,25 @@ val UnresolvedLocationLink = "#"
1919
trait Locations(using ctx: DocContext):
2020
def effectiveMembers: Map[DRI, Member]
2121

22+
// We generate this collection only if there may be a conflict with resources.
23+
// Potentially can be quite big.
24+
lazy val apiPaths = effectiveMembers.keySet.filterNot(_.isStaticFile).map(absolutePath)
25+
2226
var cache = new JHashMap[DRI, Seq[String]]()
2327

28+
private[renderers] def pathsConflictResoultionMsg =
29+
"Using `-Yapi-subdirectory` flag will move all API documentation into `api` subdirectory and will fix this conflict."
30+
2431
// TODO verify if location exisits
2532
def rawLocation(dri: DRI): Seq[String] =
2633
cache.get(dri) match
2734
case null =>
2835
val path = dri match
2936
case `docsRootDRI` => List("docs", "index")
30-
case `apiPageDRI` => List("api", "index")
37+
case `apiPageDRI` =>
38+
if ctx.args.apiSubdirectory || ctx.staticSiteContext.fold(false)(_.hasIndexFile)
39+
then List("api", "index")
40+
else List("index")
3141
case dri if dri.isStaticFile =>
3242
Paths.get(dri.location).iterator.asScala.map(_.toString).toList
3343
case dri =>
@@ -36,8 +46,7 @@ trait Locations(using ctx: DocContext):
3646
case "<empty>" :: Nil => "_empty_" :: Nil
3747
case "<empty>" :: tail => "_empty_" :: tail
3848
case other => other
39-
40-
Seq("api") ++ fqn
49+
if ctx.args.apiSubdirectory then "api" :: fqn else fqn
4150
cache.put(dri, path)
4251
path
4352
case cached => cached

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

Lines changed: 20 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -171,19 +171,23 @@ trait Resources(using ctx: DocContext) extends Locations, Writer:
171171
)
172172

173173
def renderResource(resource: Resource): Seq[String] =
174-
resource match
175-
case Resource.Text(path, content) =>
176-
Seq(write(path, content))
177-
case Resource.Classpath(path, name) =>
178-
getClass.getClassLoader.getResourceAsStream(name) match
179-
case null =>
180-
report.error(s"Unable to find $name on classpath")
181-
Nil
182-
case is =>
183-
try Seq(copy(is, path)) finally is.close()
184-
case Resource.File(path, file) =>
185-
Seq(copy(file, path))
186-
case Resource.URL(url) =>
187-
Nil
188-
case Resource.URLToCopy(url, dest) =>
189-
Seq(copy(new URL(url).openStream(), dest))
174+
if resource.path.endsWith(".html") && apiPaths.contains(resource.path) then
175+
report.error(s"Conflict between resource and API member for ${resource.path}. $pathsConflictResoultionMsg")
176+
Nil
177+
else
178+
resource match
179+
case Resource.Text(path, content) =>
180+
Seq(write(path, content))
181+
case Resource.Classpath(path, name) =>
182+
getClass.getClassLoader.getResourceAsStream(name) match
183+
case null =>
184+
report.error(s"Unable to find $name on classpath")
185+
Nil
186+
case is =>
187+
try Seq(copy(is, path)) finally is.close()
188+
case Resource.File(path, file) =>
189+
Seq(copy(file, path))
190+
case Resource.URL(url) =>
191+
Nil
192+
case Resource.URLToCopy(url, dest) =>
193+
Seq(copy(new URL(url).openStream(), dest))

‎scaladoc/src/dotty/tools/scaladoc/site/StaticSiteContext.scala‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -19,17 +19,21 @@ class StaticSiteContext(
1919

2020
var memberLinkResolver: String => Option[DRI] = _ => None
2121

22-
def indexTemplate(): LoadedTemplate =
22+
private def indexFiles =
2323
val files = List(new File(root, "index.html"), new File(root, "index.md")).filter { _.exists() }
2424

2525
if files.size > 1 then
2626
val msg = s"ERROR: Multiple root index pages found: ${files.map(_.getAbsolutePath)}"
2727
report.error(msg)
28+
files
2829

29-
files.flatMap(loadTemplate(_, isBlog = false)).headOption.getOrElse {
30-
val fakeFile = new File(root, "index.html")
31-
LoadedTemplate(emptyTemplate(fakeFile, "index"), List.empty, fakeFile)
32-
}
30+
def hasIndexFile = indexFiles.nonEmpty
31+
32+
def emptyIndexTemplate =
33+
val fakeFile = new File(root, "index.html")
34+
LoadedTemplate(emptyTemplate(fakeFile, "index"), List.empty, fakeFile)
35+
36+
def indexTemplates(): Seq[LoadedTemplate] = indexFiles.flatMap(loadTemplate(_, isBlog = false))
3337

3438
lazy val layouts: Map[String, TemplateFile] =
3539
val layoutRoot = new File(root, "_layouts")

0 commit comments

Comments
 (0)