Add missing features to scala3doc to match dotty docs #10320

romanowski · 2020-11-15T01:29:58Z

Links do generated documentation using this PR for Scala 3 and scal3doc itself (however it has just a token static site).

Scope of this PR:

render index page for blog
blogposts has all required parameters
render images properly in static site/blog
search bar is flating
Add properties for version, revision etc.
edit on github links does not work
linking from static pages to types
linking to paragraphs
ensure that we document all the classes that are documented on https://dotty.epfl.ch/

Known differences:

navigation is a bit different but allow for adding content of each level (so e.g. https://dotty.epfl.ch/docs/reference/overview.html can be moved directly to Reference node: https://scala3doc.virtuslab.com/pr-10320/scala3/docs/Reference/index.html)
searchbar is dynamic and is able to search in titles of static pages and blogs however we do search for packages (however I am pretty sure @pikinier20 will be able to make this work)
For now we do not support includes in static documentation but this is a matter of day or two (documentation for scala 3 uses it on main page and to add a table of conent on one page)
We do not support (but shoudl not be hard to implement if needed) rendering of docstrings in static doumentation but this is not used in Scala 3 documentation
Scala3doc doesn not come with predefined layouts. images and includse for static documentation. Once we migrate Scala 3 documentaiton we plan to reach out to community to ask what kind of defaults are expected.
TODO: inspect other differneces

New features:

[site] sidebar can have arbitrary deps, sections (directories) can have its own content (in index.html or index.md)
scala3doc cover all language features (bug in givens is being fixed by @pikinier20)
scala3doc has members filter (improved version of one in scaladoc)
members in scala3doc is groped by kind and origin (defined and inherited) and in future we can apply arbitraty (also dynamic) groupping
scala3doc provides subset of implicit members (from extension methods, given and implicit conversions) however this is really a naive implemtnation
scala3doc provide linear subtypes and type hierarchy diagrams (https://scala3doc.virtuslab.com/pr-10298/scala3/api/scala/-empty-tuple/index.html)
scala3doc is fast and reuses compilation artifacts. It takes under 20s seconds on my machine to generate documentation for Scala 3 once code is compiled. Scala3doc was not optimized at any point so I am sure we can be even faster
scala3doc has proper implementation of linking to sources that even more powerfull then scaladoc (allows to provide custom patterns as well as partial patterns for subrepositories or documentation compose from various repositories)
scala3doc has abstract and unified mechanism for linking to pages based on DRIs that will allow us to link to documentation from other projects
scala3doc properly parsers doc comments (this includes linking etc.)
scala3doc allow to cusomize logo and has its own custom logo :)

- add links - implement more generic children mechanism

To not refactor half of model I needed to use a var that accepts lambda. We should probably find better way to do it (probably by processing TASTY before we start dokka) Add local alias for DRI

also expost it as fields in static site

Set cwd form generate*Documentation tasks to root project path

BarkingBad

So far look good

BarkingBad · 2020-11-16T11:36:24Z

scala3doc/src/dotty/dokka/site/LoadedTemplate.scala

+import scala.collection.JavaConverters._
+
+
+case class LazyEntry(val getKey: String, value: () => String) extends JMapEntry[String, Object]:


Redundant val

This makes our source link precisily pin-point used source not what is currently on master.

abgruszecki · 2020-11-17T20:15:46Z

scala3doc/src/dotty/dokka/site/common.scala

-      EmojiExtension.ROOT_IMAGE_PATH,
-      "https://github.global.ssl.fastly.net/images/icons/emoji/"
-    )
+    .set(Parser.INDENTED_CODE_BLOCK_PARSER, false)


Do we intentionally disable indented code blocks?

I copied the settings over from dotty-doc so I do not have a strong feeling aboout any of this options beside ANCHORLINKS ones.

I think we should support them, unless we have a reason not to.

There's a separate topic here: linking to documentation from static site should be done with Wiki links, like in doc comments. This requires the WikiLink extension like here and some link-handling code that's already in MarkdownConverter here.

abgruszecki

Aside from the comments, LGTM!

abgruszecki · 2020-11-17T22:53:48Z

scala3doc/src/dotty/dokka/tasty/TastyParser.scala

+    config.staticSiteContext.foreach { p =>
+      val previous = p.memberLinkResolver
+      p.memberLinkResolver = link => previous(link).orElse(driFor(link))
+    }


It shouldn't be neccessary to store multiple contexts, any of them should work for resolving links.

abgruszecki · 2020-11-17T23:01:41Z

scala3doc/src/dotty/dokka/site/common.scala

-      EmojiExtension.ROOT_IMAGE_PATH,
-      "https://github.global.ssl.fastly.net/images/icons/emoji/"
-    )
+    .set(Parser.INDENTED_CODE_BLOCK_PARSER, false)


I think we should support them, unless we have a reason not to.

There's a separate topic here: linking to documentation from static site should be done with Wiki links, like in doc comments. This requires the WikiLink extension like here and some link-handling code that's already in MarkdownConverter here.

Do not fail on missing link but display a warning.

romanowski force-pushed the scala3doc/dotty-doc-parity branch from 028bb16 to 40cf93e Compare November 15, 2020 09:08

BarkingBad and others added 10 commits November 16, 2020 10:50

Add blog posts summary index page

f0bfd07

Blog improvments

9124767

- add links - implement more generic children mechanism

Search icon is floating

ec2a0e9

Render absolute paths for images in static sites

233ec74

hack support for member links in static pages

35598dc

To not refactor half of model I needed to use a var that accepts lambda. We should probably find better way to do it (probably by processing TASTY before we start dokka) Add local alias for DRI

Add support to anchorlinks in .md file

b80924b

Add scala3doc logo and fix link

52d238e

Use provided name, logo and projectVersion

470413c

also expost it as fields in static site

Add view and edit links to static pages

f8ae203

Set cwd form generate*Documentation tasks to root project path

Fix TemplateFileTest

7fce442

romanowski force-pushed the scala3doc/dotty-doc-parity branch from 2a0cc49 to 7fce442 Compare November 16, 2020 09:50

Fix line from sources

d7d9606

BarkingBad approved these changes Nov 16, 2020

View reviewed changes

Code cleanup

6aed05c

romanowski marked this pull request as ready for review November 16, 2020 12:06

Documentation of scala3doc uses commit hash

3af2320

This makes our source link precisily pin-point used source not what is currently on master.

This was referenced Nov 17, 2020

Show project version in the docs lampepfl/scala3doc#131

Closed

What about the Dotty blog? lampepfl/scala3doc#160

Closed

Edit on github points to hosting lampepfl/scala3doc#147

Closed

abgruszecki reviewed Nov 17, 2020

View reviewed changes

Fixes for rendering link to documentation

312517d

Do not fail on missing link but display a warning.

This was referenced Nov 18, 2020

Use scala3 doc to generate dotty website #10373

Merged

Add blog posts summary index page #10312

Closed

abgruszecki approved these changes Nov 18, 2020

View reviewed changes

abgruszecki merged commit 8963e5f into scala:master Nov 18, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add missing features to scala3doc to match dotty docs #10320

Add missing features to scala3doc to match dotty docs #10320

Uh oh!

romanowski commented Nov 15, 2020 •

edited

Loading

Uh oh!

BarkingBad left a comment

Uh oh!

BarkingBad Nov 16, 2020

Uh oh!

abgruszecki Nov 17, 2020

Uh oh!

romanowski Nov 17, 2020

Uh oh!

abgruszecki Nov 17, 2020

Uh oh!

abgruszecki left a comment

Uh oh!

abgruszecki Nov 17, 2020

Uh oh!

abgruszecki Nov 17, 2020

Uh oh!

Uh oh!

		import scala.collection.JavaConverters._


		case class LazyEntry(val getKey: String, value: () => String) extends JMapEntry[String, Object]:

Add missing features to scala3doc to match dotty docs #10320

Add missing features to scala3doc to match dotty docs #10320

Uh oh!

Conversation

romanowski commented Nov 15, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

BarkingBad left a comment

Choose a reason for hiding this comment

Uh oh!

BarkingBad Nov 16, 2020

Choose a reason for hiding this comment

Uh oh!

abgruszecki Nov 17, 2020

Choose a reason for hiding this comment

Uh oh!

romanowski Nov 17, 2020

Choose a reason for hiding this comment

Uh oh!

abgruszecki Nov 17, 2020

Choose a reason for hiding this comment

Uh oh!

abgruszecki left a comment

Choose a reason for hiding this comment

Uh oh!

abgruszecki Nov 17, 2020

Choose a reason for hiding this comment

Uh oh!

abgruszecki Nov 17, 2020

Choose a reason for hiding this comment

Uh oh!

Uh oh!

romanowski commented Nov 15, 2020 •

edited

Loading