Doctool: Extra "api" directory under target

[eed3si9n]

Compiler version

3.0.0-M4-bin-20210212-0273336-NIGHTLY

Minimized code

package foo

final val foo = "Foo"

object A:
  /**
   * @param i An argument
   */
  def x(i:Int)=3

Then run doc from sbt 1.5.0-M2.

Output

It creates target/scala-3.0.0-M4/api/api directory.
For example target/scala-3.0.0-M4/api/api/foo/A$.html.

Expectation

I expect HTML files to be under target/scala-3.0.0-M4/api/ directory. Note that the term api is set by sbt as Compile/doc/target.

See the output of Scala 2.x's output - https://scopt.github.io/scopt/4.0.0/api/index.html

Directly under api/ it would create directory names corresponding to the package like scopt, and https://scopt.github.io/scopt/4.0.0/api/scopt/index.html would list the classes under scopt package.

[eed3si9n]

cc @romanowski, @pikinier20

[pikinier20]

@romanowski Maybe we should adjust our directory structure to match old scaladoc. If that is the case, we should move our resources inside lib/ folder and move documentation to root folder. I only wonder what to do in case when there's lib package in project because it leads to name conflict.

[eed3si9n]

Maybe you could use a reserve word like object/.

[abgruszecki]

@eed3si9n can you clarify what exactly is the problem with having two api directories?

[eed3si9n]

Scaladoc is meant to be published to the web. Whenever possible we should maintain the backward compatibility of the URL since these pages are often linked from Stackoverflow or documentations.

[abgruszecki]

@romanowski what's our current position on full backwards link compat with old Scaladoc?

[SethTisue]

did #13130 affect this?

[BarkingBad]

I guess #13130 should have "fixed" the issue (I can confirm that and close it tomorrow). At least as long as someone doesn't run the scaladoc with -Yapi-subdirectory setting toggled on.

[BarkingBad]

I just checked it and indeed, the default behaviour now is to skip the api subdirectory, unless someone provides -Yapi-subdirectory flag, so I guess the issue is resolved. On the other hand, you demand to have index.html listing members of the package. Currently, if you have package foo.bar the listing will be under foo/bar.html. I don't know if we should change it.