search

scala / scala3

The Scala 3 compiler, also known as Dotty.
https://dotty.epfl.ch
Apache License 2.0
5.81k stars 1.05k forks source link

Scaladoc converts all relative links to html #11702

Closed jodersky closed 3 years ago

jodersky commented 3 years ago

Compiler version

RC1

Minimized code

Any markdown that has a link to another local file. Scaladoc will always strip the extension and add '.html'. This results in invalid links if the original link points to other static files that will not be converted to html.

E.g. assume the following files:

foo.pdf
content.md

where content.md:

look at the documentation [here](foo.pdf)

Output

content.html will have a link to foo.html, which does not exist.

Expectation

content.html should have a link to foo.pdf

BarkingBad commented 3 years ago

It's partially a bug. It should work when the resource indeed exists at given location. Otherwise there is a bug in fallback strategy, that assumes that it has to be link to the scala element (class, method, etc.) but it doesn't check whether that made up "class" or "method" actually exists.

On the other hand I think we didn't support yet copying static resources, so it will always fail for local elements, because it won't find them, therefore assume it is DRI link, will make .html extension and so on...

Nonetheless, we should fix the check (Locations.scala:84) and support local resources.

jodersky commented 3 years ago

thanks for clarifying. What is a "DRI link"?

BarkingBad commented 3 years ago

DRI is an identifier to formerly mentioned "class" or "method" or any other construct worth documenting. It name is inherited from dokka doctool, on which new scaladoc used to be based on. It stands for Dokka Resource Identifier. As for now, we removed dokka dependency (since it is too heavy for our needs), so the name can change in the near future.

BarkingBad commented 3 years ago

Sorry for the long waiting time @jodersky

I added extra directory inside docs root directory called resources. The semantic is identical to images directory. Please place all your static resources like pdfs etc. under that directory and in code reference them by [here](/resources/foo.pdf)