Improve how modules are merged - relativePathToOutputDirectory can't handle a module that is not a child

[aSemy]

Describe the bug

DokkaModuleDescription.relativePathToOutputDirectory is used by Dokka when aggregating Dokka Modules into a single directory.

The value is used to create subdirectories in the Dokka output directory. For example, if there are two modules, where relativePathToOutputDirectory is childProjectA one and childProjectB in another, there will be equivalent subdirectories in the result.

build/
├── htmlMultiModule/
│   ├── childProjectA/
│   │   ├── index.html
│   │   └── ...
│   └── childProjectB/
│       ├── index.html
│       └── ...
├── index.html
└── ...

The value of relativePathToOutputDirectory is determined automatically by the relative path between the aggregating project and the module.

• dokka/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaMultiModuleTask.kt

  Lines 93 to 98 in daed35f

  	DokkaModuleDescriptionImpl(
  	name = dokkaTask.moduleName.getSafe(),
  	relativePathToOutputDirectory = targetChildOutputDirectory(dokkaTask).relativeTo(outputDirectory.getSafe()),
  	includes = childDokkaTaskIncludes[dokkaTask.path].orEmpty(),
  	sourceOutputDirectory = dokkaTask.outputDirectory.getSafe()
  	)

• dokka/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaMultiModuleFileLayout.kt

  Lines 36 to 43 in daed35f

  	object CompactInParent : DokkaMultiModuleFileLayout {
  	override fun targetChildOutputDirectory(parent: DokkaMultiModuleTask, child: AbstractDokkaTask): File {
  	val relativeProjectPath = parent.project.relativeProjectPath(child.project.path)
  	val relativeFilePath = relativeProjectPath.replace(":", File.separator)
  	check(!File(relativeFilePath).isAbsolute) { "Unexpected absolute path $relativeFilePath" }
  	return parent.outputDirectory.getSafe().resolve(relativeFilePath)
  	}
  	}

This is problematic because it cannot handle modules that are not in child directories. For example, if the aggregating project is not a direct parent of the children

project/
├── docs/
│   └── build.gradle.kts <- Dokka site is created here
├── parentProject/
│   ├── childProjectA/
│   │   └── build.gradle.kts
│   └── childProjectB/
│       └── build.gradle.kts
└── settings.gradle.kts

Additionally:

• The variable name relativePathToOutputDirectory is confusing - it's more like "the relative path INSIDE the output directory" or "moduleDocPath" or just "modulePath".
• Is it necessary? Can't the directory default to the module's name?
• There are no docs! Not in the code, and not on the website. Figuring this out was difficult
• It is a java.io.File. It's tempting to pass in a relative path (e.g. ../parentProject/childProjectA) or an absolute path (e.g. /usr/x/projects/my-project/docs/build/dokka/childProjectA) - both are wrong. It should just be a plain string.
• Trying to use a nested path, e.g. relativePathToOutputDirectory = File("some/path") doesn't work because mkdir() is used
  

  dokka/plugins/templating/src/main/kotlin/templates/TemplateProcessor.kt

  Line 56 in daed35f

  target.mkdir()

Expected behaviour

• relativePathToOutputDirectory is renamed to be more descriptive,
• and replaced with a String,
• or removed and just use DokkaModuleDescription.name instead.
• mkdir() is replaced with mkdirs()

Installation

• Build tool: Gradle v7.6
• Dokka version: 1.7.20

Additional context

Fixing this would help with #2700