Skip to content

Refactor: Improve error messaging in sidebar YAML parser #17229

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Jun 12, 2023
Merged

Refactor: Improve error messaging in sidebar YAML parser #17229

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
b8d5207
Improve error messaging in sidebar YAML parser
Dedelweiss Apr 3, 2023
dd5ebcc
Corrections:
Dedelweiss May 8, 2023
3ce49f8
Add tests
Dedelweiss May 8, 2023
cfa4461
Add a first test:
Dedelweiss May 9, 2023
e9719f6
Corrections:
Dedelweiss May 10, 2023
49d3c62
Add the page to title missing error
Dedelweiss May 12, 2023
5e7e205
Avoid re-parse and change errors messages
Dedelweiss May 26, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 35 additions & 7 deletions scaladoc/src/dotty/tools/scaladoc/site/SidebarParser.scala
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ import com.fasterxml.jackson.core.`type`.TypeReference;
import scala.jdk.CollectionConverters._
import java.util.Optional
import scala.beans._
import java.nio.file.{Files, Paths}
import scala.io.Source

enum Sidebar:
case Category(
Expand All @@ -30,16 +32,43 @@ object Sidebar:

private object RawInputTypeRef extends TypeReference[RawInput]

private def toSidebar(r: RawInput)(using CompilerContext): Sidebar = r match
private def pageWithNoTitle(content: String | java.io.File): String =
val fileContent = content match {
case file: java.io.File => Source.fromFile(file).getLines().mkString("\n")
case str: String => str
}
val lines = fileContent.split("\n")
lines.zipWithIndex
.find { case (line, i) => line.trim.startsWith("page:") && !lines(i - 1).contains("- title:") }
.map(_._1.trim.stripPrefix("page:"))
.getOrElse("")

private def toSidebar(r: RawInput, content: String | java.io.File)(using CompilerContext): Sidebar = r match
case RawInput(title, page, index, subsection, dir, hidden) if page.nonEmpty && index.isEmpty && subsection.isEmpty() =>
val sidebarPath = content match
case s: String => Paths.get(s)
case f: java.io.File => f.toPath()
val basePath = sidebarPath.getParent().resolve("_docs")
val pagePath = basePath.resolve(page)
if !Files.exists(pagePath) then
report.error(s"Page $page does not exist.")
Sidebar.Page(Option.when(title.nonEmpty)(title), page, hidden)
case RawInput(title, page, index, subsection, dir, hidden) if page.isEmpty && (!subsection.isEmpty() || !index.isEmpty()) =>
Sidebar.Category(Option.when(title.nonEmpty)(title), Option.when(index.nonEmpty)(index), subsection.asScala.map(toSidebar).toList, Option.when(dir.nonEmpty)(dir))
Sidebar.Category(Option.when(title.nonEmpty)(title), Option.when(index.nonEmpty)(index), subsection.asScala.map(toSidebar(_, content)).toList, Option.when(dir.nonEmpty)(dir))
case RawInput(title, page, index, subsection, dir, hidden) =>
report.error(s"Error parsing YAML configuration file.\n$schemaMessage")
if title.isEmpty() && index.isEmpty() then
val page = pageWithNoTitle(content).trim()
val msg = s"Error parsing YAML configuration file: 'title' is not provided for page '$page'."
report.error(s"$msg\n$schemaMessage")
else if title.nonEmpty && (page.isEmpty() || index.isEmpty()) then
val msg = s"Error parsing YAML configuration file: 'index' or 'page' path is missing for title '$title'."
report.error(s"$msg\n$schemaMessage")
else
val msg = s"Error parsing YAML configuration file."
report.warning(s"$msg\n$schemaMessage")
Sidebar.Page(None, page, hidden)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why do we still return a Sidebar even though we reported errors?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Indeed, I think there's a problem with this return. Because we need to return the Sidebar type but with Sidebar.Page(None, page, hidden). When a user forgets a page associated with a title like :

index: index.md
subsection :
  - title : My title
  - page: my-page2.md

This sends an error but also blocks the generation of all the documentation (which is rather extreme).
See if I can return Sidebar.Category(None, None, Nil, None) instead.


private def schemaMessage: String =
def schemaMessage: String =
s"""Static site YAML configuration file should comply with the following description:
|The root element of static site needs to be <subsection>
|`title` and `directory` properties are ignored in root subsection.
Expand All @@ -57,8 +86,7 @@ object Sidebar:
| hidden: <boolean> # optional - Default value is false.
|
|For more information visit:
|https://docs.scala-lang.org/scala3/guides/scaladoc/static-site.html
|""".stripMargin
|https://docs.scala-lang.org/scala3/guides/scaladoc/static-site.html""".stripMargin

def load(content: String | java.io.File)(using CompilerContext): Sidebar.Category =
import scala.util.Try
Expand All @@ -75,7 +103,7 @@ object Sidebar:
},
identity
)
toSidebar(root) match
toSidebar(root, content) match
case c: Sidebar.Category => c
case _ =>
report.error(s"Root element is not a subsection.\n$schemaMessage")
Expand Down
86 changes: 85 additions & 1 deletion scaladoc/test/dotty/tools/scaladoc/site/SidebarParserTest.scala
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,12 @@ package site

import org.junit.Test
import org.junit.Assert._
import dotty.tools.scaladoc.site.Sidebar
import dotty.tools.scaladoc.site.Sidebar.RawInput
import java.io.ByteArrayOutputStream
import java.io.PrintStream

// TODO add negaitve and more details tests
// TODO add negative and more details tests
class SidebarParserTest:

private val sidebar =
Expand Down Expand Up @@ -34,6 +38,64 @@ class SidebarParserTest:
| - page: my-page6/my-page6/my-page6.md
""".stripMargin

private val sidebarNoTitle =
"""index: index.md
|subsection:
| - title: My title
| page: my-page1.md
| - page: my-page2.md
| - page: my-page3/subsection
| - title: Reference
| subsection:
| - page: my-page3.md
| hidden: true
| - index: my-page4/index.md
| subsection:
| - page: my-page4/my-page4.md
| - title: My subsection
| index: my-page5/index.md
| subsection:
| - page: my-page5/my-page5.md
| - subsection:
| page: my-page7/my-page7.md
| - index: my-page6/index.md
| subsection:
| - index: my-page6/my-page6/index.md
| subsection:
| - page: my-page6/my-page6/my-page6.md
""".stripMargin

private val sidebarErrorNoPage =
"""index: index.md
|subsection:
| - title: My title
| - page: my-page2.md
| - page: my-page3/subsection
| - title: Reference
| subsection:
| - page: my-page3.md
| hidden: true
| - index: my-page4/index.md
| subsection:
| - page: my-page4/my-page4.md
| - title: My subsection
| index: my-page5/index.md
| subsection:
| - page: my-page5/my-page5.md
| - subsection:
| - page: my-page7/my-page7.md
| - index: my-page6/index.md
| subsection:
| - index: my-page6/my-page6/index.md
| subsection:
| - page: my-page6/my-page6/my-page6.md
""".stripMargin

private val msgNoTitle = "Error parsing YAML configuration file: 'title' is not provided for page 'my-page7/my-page7.md'."
private val msgNoPage = "Error parsing YAML configuration file: 'index' or 'page' path is missing for title 'My title'."

private def schemaMessage: String = Sidebar.schemaMessage

@Test
def loadSidebar(): Unit = assertEquals(
Sidebar.Category(
Expand All @@ -53,3 +115,25 @@ class SidebarParserTest:
),
Sidebar.load(sidebar)(using testContext)
)

@Test
def loadSidebarNoPageError: Unit =
val out = new ByteArrayOutputStream()
Console.withErr(new PrintStream(out)) {
Sidebar.load(sidebarErrorNoPage)(using testContext)
}
println(out.toString())
val error = out.toString().trim()

assert(error.contains(msgNoPage) && error.contains(schemaMessage))


@Test
def loadSidebarNoTitleError(): Unit =
val out = new ByteArrayOutputStream()
Console.withErr(new PrintStream(out)) {
Sidebar.load(sidebarNoTitle)(using testContext)
}
val error = out.toString().trim()

assert(error.contains(msgNoTitle) && error.contains(schemaMessage))