diff --git a/.github/workflows/scaladoc.yaml b/.github/workflows/scaladoc.yaml index 19607bac3065..f91c51b85c85 100644 --- a/.github/workflows/scaladoc.yaml +++ b/.github/workflows/scaladoc.yaml @@ -64,9 +64,9 @@ jobs: with: inlineScript: | DOC_DEST=pr-${PR_NUMBER:-${GITHUB_REF##*/}} - echo uplading docs to https://scaladoc.virtuslab.com/$DOC_DEST - az storage container create --name $DOC_DEST --account-name scaladocstorage --public-access container - az storage blob sync -s scaladoc/output -c $DOC_DEST --account-name scaladocstorage + echo uplading docs to https://scala3doc.virtuslab.com/$DOC_DEST + az storage container create --name $DOC_DEST --account-name scala3docstorage --public-access container + az storage blob sync -s scaladoc/output -c $DOC_DEST --account-name scala3docstorage community-docs: env: @@ -77,6 +77,7 @@ jobs: && !contains(github.event.pull_request.body, '[skip docs]') ) || contains(github.event.ref, 'scaladoc') + || contains(github.event.ref, 'scala3doc') || contains(github.event.ref, 'master')" steps: @@ -102,6 +103,6 @@ jobs: with: inlineScript: | DOC_DEST=pr-${PR_NUMBER:-${GITHUB_REF##*/}}-docs - echo uplading docs to https://scaladoc.virtuslab.com/$DOC_DEST - az storage container create --name $DOC_DEST --account-name scaladocstorage --public-access container - az storage blob sync -s community-build/docsOutput -c $DOC_DEST --account-name scaladocstorage + echo uplading docs to https://scala3doc.virtuslab.com/$DOC_DEST + az storage container create --name $DOC_DEST --account-name scala3docstorage --public-access container + az storage blob sync -s community-build/docsOutput -c $DOC_DEST --account-name scala3docstorage diff --git a/docs/blog/_posts/2020-12-18-scala3-m3.md b/docs/blog/_posts/2020-12-18-scala3-m3.md index 9eee6359f77c..e0cba2b144d8 100644 --- a/docs/blog/_posts/2020-12-18-scala3-m3.md +++ b/docs/blog/_posts/2020-12-18-scala3-m3.md @@ -133,9 +133,9 @@ You can read the discussion of this change in the [PR #10670](https://github.com # Tooling improvements As we are getting closer to a stable release of Scala 3, the focus increasingly shifts on the tooling available to get started with Scala 3. -For a while now, we are not using the old dottydoc documentation tool for building the documentation. We are developing an entirely new tool, scaladoc, from scratch. This new documentation tool is more robust and faster than the old one. +For a while now, we are not using the old dottydoc documentation tool for building the documentation. We are developing an entirely new tool, scala3doc, from scratch. This new documentation tool is more robust and faster than the old one. -As part of the tooling effort, this new Scala 3 documentation tool is rapidly improved. [PR #10522](https://github.com/lampepfl/dotty/pull/10522) proves that the doctool can generate documentation for the community build projects. You can access this documentation via the following [link](https://scaladoc.virtuslab.com/pr-master-docs/index.html). +As part of the tooling effort, this new Scala 3 documentation tool is rapidly improved. [PR #10522](https://github.com/lampepfl/dotty/pull/10522) proves that the doctool can generate documentation for the community build projects. You can access this documentation via the following [link](https://scala3doc.virtuslab.com/pr-master-docs/index.html). [PR #10491](https://github.com/lampepfl/dotty/pull/10491) introduced scripting support in Scala 3. Consider the following source named `Main.scala`: diff --git a/docs/docs/usage/scaladoc/blog.md b/docs/docs/usage/scaladoc/blog.md index 4770d6514f75..14d6ff9e1de9 100644 --- a/docs/docs/usage/scaladoc/blog.md +++ b/docs/docs/usage/scaladoc/blog.md @@ -4,6 +4,6 @@ title: Built-in blog # {{page.title}} -scaladoc allows you to include a simple blog in your documentation. For now, it +Scaladoc allows you to include a simple blog in your documentation. For now, it provides only basic features. In the future, we plan to include more advanced features like tagging or author pages. diff --git a/docs/docs/usage/scaladoc/docComments.md b/docs/docs/usage/scaladoc/docComments.md index 12e93623fbd9..87ca35cba26d 100644 --- a/docs/docs/usage/scaladoc/docComments.md +++ b/docs/docs/usage/scaladoc/docComments.md @@ -4,7 +4,7 @@ title: API Documentation # {{ page.title }} -scaladoc's main feature is creating API documentation from code comments. +Scaladoc's main feature is creating API documentation from code comments. By default, the code comments are understood as Markdown, though we also support Scaladoc's old [Wiki syntax](https://docs.scala-lang.org/style/scaladoc.html). @@ -74,8 +74,8 @@ closer together. The new features are: /** TODO: Figure out what [[`([.abusive.])`]] is. */ def foo = `([.abusive.])` ``` - Scaladoc required backslash-escaping to reference such identifiers. Instead, - scaladoc allows using the familiar Scala backtick quotation. + Previously (versions 2.x), Scaladoc required backslash-escaping to reference such identifiers. Now (3.x versions), + Scaladoc allows using the familiar Scala backtick quotation. #### Why keep the Wiki syntax for links? diff --git a/docs/docs/usage/scaladoc/index.md b/docs/docs/usage/scaladoc/index.md index a13b4eab3c0b..8572ef8617b9 100644 --- a/docs/docs/usage/scaladoc/index.md +++ b/docs/docs/usage/scaladoc/index.md @@ -4,7 +4,7 @@ title: scaladoc ![scaladoc logo](/images/scaladoc-logo.png) -scaladoc is tool to generate documentation for your Scala 3 projects. It provies similar features to `javadoc` or `scaladoc` as well as `jekyll` or `docusaurus`. +scaladoc is tool to generate documentation for your Scala 3 projects. It provies similar features to `javadoc` as well as `jekyll` or `docusaurus`. As you probably have guessed, this whole site was created using scaladoc. diff --git a/docs/docs/usage/scaladoc/specificTags.md b/docs/docs/usage/scaladoc/specificTags.md index 09619f6fce94..0aa794add501 100644 --- a/docs/docs/usage/scaladoc/specificTags.md +++ b/docs/docs/usage/scaladoc/specificTags.md @@ -1,15 +1,15 @@ --- -title: scaladoc-specific Tags and Features +title: Scaladoc-specific Tags and Features --- # {{page.title}} -scaladoc extends Markdown with additional features, such as linking +Scaladoc extends Markdown with additional features, such as linking to API definitions. This can be used from within static documentation and blog posts to provide blend-in content. ## Linking to API -scaladoc allows linking to API documentation with Wiki-style links. Linking to +Scaladoc allows linking to API documentation with Wiki-style links. Linking to `scala.collection.immutable.List` is as simple as `[[scala.collection.immutable.List]]`. For more information on the exact syntax, see [doc comment documentation](./docComments.html#definition-links). diff --git a/docs/docs/usage/scaladoc/staticSite.md b/docs/docs/usage/scaladoc/staticSite.md index ec8640f986c0..b84e84716214 100644 --- a/docs/docs/usage/scaladoc/staticSite.md +++ b/docs/docs/usage/scaladoc/staticSite.md @@ -4,7 +4,7 @@ title: Static documentation # {{ page.title}} -scaladoc is able to generate static sites, known from [Jekyll](http://jekyllrb.com/) or [Docusaurus](https://docusaurus.io/). +Scaladoc is able to generate static sites, known from [Jekyll](http://jekyllrb.com/) or [Docusaurus](https://docusaurus.io/). Having a combined tool allows to provide interaction between static documentation and API, thus allowing the two to blend naturally. Creating a site is just as simple as in Jekyll. The site root contains the @@ -29,18 +29,18 @@ index.html docs/getting-started.html ``` -scaladoc can transform both files and directories (to organize your documentation into tree-like structure). By default directories has title based on file name and has empty content. There is an option to include `index.html` or `index.md` (not both) to provide both content and properties like title (see [Properties](#properties)). +Scaladoc can transform both files and directories (to organize your documentation into tree-like structure). By default directories has title based on file name and has empty content. There is an option to include `index.html` or `index.md` (not both) to provide both content and properties like title (see [Properties](#properties)). ## Properties -scaladoc uses the [Liquid](https://shopify.github.io/liquid/) templating engine +Scaladoc uses the [Liquid](https://shopify.github.io/liquid/) templating engine and provides a number of custom filters and tags specific to Scala documentation. -In scaladoc, all templates can contain YAML front-matter. The front-matter +In Scaladoc, all templates can contain YAML front-matter. The front-matter is parsed and put into the `page` variable available in templates via Liquid. -scaladoc uses some predefined properties to controls some aspect of page. +Scaladoc uses some predefined properties to controls some aspect of page. Predefined properties: @@ -94,7 +94,7 @@ Layouts must be placed in a `_layouts` directory in the site root: Sidebar ======= -scaladoc by default uses layout of files in `docs` directory to create table of content. There is also ability to override it by providing a `sidebar.yml` file in the site root: +Scaladoc by default uses layout of files in `docs` directory to create table of content. There is also ability to override it by providing a `sidebar.yml` file in the site root: ```yaml sidebar: diff --git a/docs/sidebar.yml b/docs/sidebar.yml index a1566f7cdd86..9450d3b41eb7 100644 --- a/docs/sidebar.yml +++ b/docs/sidebar.yml @@ -15,7 +15,7 @@ sidebar: url: docs/usage/language-versions.html - title: cbt-projects url: docs/usage/cbt-projects.html - - title: scaladoc + - title: Scaladoc url: docs/usage/scaladoc - title: Dottydoc [Legacy] url: docs/usage/dottydoc.html diff --git a/project/Build.scala b/project/Build.scala index 498100b686db..f015bd7760f5 100644 --- a/project/Build.scala +++ b/project/Build.scala @@ -1535,7 +1535,10 @@ object Build { def generateDocumentation(targets: String, name: String, outDir: String, ref: String, params: String = "") = Def.taskDyn { val projectVersion = version.value IO.createDirectory(file(outDir)) - val sourceLinks = "-source-links:github://lampepfl/dotty " + val scala3version = stdlibVersion(Bootstrapped) + // TODO add versions etc. + val srcManaged = s"out/bootstrap/stdlib-bootstrapped/scala-$baseVersion/src_managed/main/scala-library-src" + val sourceLinks = s"-source-links:$srcManaged=github://scala/scala/v$scala3version#src/library -source-links:github://lampepfl/dotty" val revision = s"-revision $ref -project-version $projectVersion" val cmd = s""" -d $outDir -project "$name" $sourceLinks $revision $params $targets""" run.in(Compile).toTask(cmd) @@ -1611,7 +1614,7 @@ object Build { }.dependsOn(generateDocumentation( roots, "Scala 3", dest.getAbsolutePath, "master", // contains special definitions which are "transplanted" elsewhere - // and which therefore confuse scaladoc when accessed from this pkg + // and which therefore confuse Scaladoc when accessed from this pkg "-skip-by-id:scala.runtime.stdLibPatches " + // MatchCase is a special type that represents match type cases, // Reflect doesn't expect to see it as a standalone definition diff --git a/sbt-dotty/sbt-test/sbt-dotty/scaladoc/build.sbt b/sbt-dotty/sbt-test/sbt-dotty/scaladoc/build.sbt index 48a5cdce6ce8..628e6ef687dc 100644 --- a/sbt-dotty/sbt-test/sbt-dotty/scaladoc/build.sbt +++ b/sbt-dotty/sbt-test/sbt-dotty/scaladoc/build.sbt @@ -1,7 +1,7 @@ scalaVersion := sys.props("plugin.scalaVersion") -lazy val assertUsingscaladoc = taskKey[Unit]("") +lazy val assertUsingScaladoc = taskKey[Unit]("") -assertUsingscaladoc := { +assertUsingScaladoc := { assert(useScaladoc.value) } diff --git a/sbt-dotty/sbt-test/sbt-dotty/scaladoc/test b/sbt-dotty/sbt-test/sbt-dotty/scaladoc/test index ea79f0b981ca..62f36e165df0 100644 --- a/sbt-dotty/sbt-test/sbt-dotty/scaladoc/test +++ b/sbt-dotty/sbt-test/sbt-dotty/scaladoc/test @@ -1,3 +1,3 @@ -> assertUsingscaladoc +> assertUsingScaladoc > doc diff --git a/scaladoc/README.md b/scaladoc/README.md index ebf81a945865..ad5a6c0247e5 100644 --- a/scaladoc/README.md +++ b/scaladoc/README.md @@ -1,9 +1,9 @@ -# scaladoc +# Scaladoc -scaladoc (name subject to change) is the documentation tool for -[Dotty](https://github.com/lampepfl/dotty), which is scheduled to become +Scaladoc is the documentation tool for +[Scala 3](https://github.com/lampepfl/dotty), which is scheduled to become Scala 3. It uses the TastyInspector to access definitions, -which is an officially supported way to access Dotty's perspective of a +which is an officially supported way to access Scala 3's perspective of a codebase. We're aiming to support all the features Scaladoc did, plus new and exciting ones such as: @@ -57,24 +57,24 @@ work on the project. For every PR, we build documentation for scaladoc and Dotty. For example, for PR 123 you can find them at: -- -- -- +- +- +- Note that these correspond to the contents of `output` directory - that's precisely what they are. You can also find the result of building the same sites for latest `master` at: -- -- -- +- +- +- ### Testing Most tests rely on comparing signatures (of classes, methods, objects etc.) extracted from the generated documentation -to signatures found in source files. Such tests are defined using [MultipleFileTest](test/dotty/tools/scaladoc/MultipleFileTest.scala) class -and its subtypes (such as [SingleFileTest](test/dotty/tools/scaladoc/SingleFileTest.scala)) +to signatures found in source files. Such tests are defined using [MultipleFileTest](test/dotty/tools/scala3doc/MultipleFileTest.scala) class +and its subtypes (such as [SingleFileTest](test/dotty/tools/scala3doc/SingleFileTest.scala)) WARNING: As the classes mentioned above are likely to evolve, the description below might easily get out of date. In case of any discrepancies rely on the source files instead. diff --git a/scaladoc/e2e/README.md b/scaladoc/e2e/README.md index 2851a079cbb0..b9f088cd7198 100644 --- a/scaladoc/e2e/README.md +++ b/scaladoc/e2e/README.md @@ -1,4 +1,4 @@ -## scaladoc e2e test suite +## Scaladoc e2e test suite ### Prerequisites diff --git a/scaladoc/src/dotty/tools/scaladoc/DocContext.scala b/scaladoc/src/dotty/tools/scaladoc/DocContext.scala index 4daf142c2f77..ccfbc25d8b70 100644 --- a/scaladoc/src/dotty/tools/scaladoc/DocContext.scala +++ b/scaladoc/src/dotty/tools/scaladoc/DocContext.scala @@ -44,7 +44,7 @@ private def sourcePostionFor(f: File)(using CompilerContext) = val sourceFile = new SourceFile(virtualFile, Codec.UTF8) SourcePosition(sourceFile, Spans.NoSpan) -// TODO (https://github.com/lampepfl/scaladoc/issues/238): provide proper error handling +// TODO (https://github.com/lampepfl/scala3doc/issues/238): provide proper error handling private def createMessage( msg: String, file: File, e: Throwable | Null)(using CompilerContext): String = val localizedMessage = s"$file: $msg" diff --git a/scaladoc/src/dotty/tools/scaladoc/SourceLinks.scala b/scaladoc/src/dotty/tools/scaladoc/SourceLinks.scala index 6ff5beeb7300..825f1dba4060 100644 --- a/scaladoc/src/dotty/tools/scaladoc/SourceLinks.scala +++ b/scaladoc/src/dotty/tools/scaladoc/SourceLinks.scala @@ -143,8 +143,8 @@ object SourceLinks: | - | | is a format for `doc-source-url` parameter scaladoc. - |NOTE: We only supports `€{FILE_PATH_EXT}` and €{FILE_LINE} patterns - | + |NOTE: We only supports `€{FILE_PATH_EXT}`, `€{TPL_NAME}`, `€{FILE_EXT}`, + | €{FILE_PATH}, and €{FILE_LINE} patterns | | |Template can defined only by subset of sources defined by path prefix represented by ``.