Am 11.12.2017 um 11:00 schrieb Jonathan M Davis:

By default, dub --build=docs takes all of the modules in the project and generates the corresponding .html files but does not retain the package hierarchy. You just get a bunch of .html files in the same folder with the file names matching the corresponding source files. That's not particularly ideal under any circumstances, but it's a huge problem if there are modules with the same name in different packages, and it does not lend itself to having ddoc macros for generating links between symbols in the project. Is there any way to get dub to put them in folders that match the actual source code? Barring that, is there a way to make the file names contain the source hierarchy but with underscores in their names to replace the slashes (like Phobos does)?

It looks like this is partly dmd's fault, because it just uses the module names for the file names, but I would expect that dub could be made to do the documentation build in a way that properly retains the package hierarchy. Is there any way to do that now, or would it require improvements to dub? Right now, it's looking like I won't be able to use dub to build documentation for my projects if I want to retain the package hierarchy.

Currently there is no way to officially override the default behavior,
which is partially founded in the support of the default all-at-once
build mode. In theory the single-file mode could depart from this, but
I'd rather move forward with a dedicated "dub docs" command, which would
also get rid of the dub -b ddox special case.

A potential workaround could be to customize the "docs" build mode and
then run with dub -b docs --build-mode=singleFile:

"buildModes": {
	"docs": {
		"buildOptions": ["syntaxOnly", "_docs"],
		"dflags": ["-op"]
	}
}

I haven't tested this, though, and there might be something that I'm not
thinking of right now that interferes with this approach. I'm also not
quite sure if -op even influences the documentation output.