Right now, when generating the documentation for a .d file with -D and -Dd, an .html file with a corresponding name (but with .html instead of .d) is generated. The Package hierarchy is compeletly ingnored in the process. If you have a/b/c.d, and you generate documentation for it, you get c.html, not a/b/c.html, which makes it way more of a pain to deal with generating links in your documentation. It's also a serious problem if you have any modules in different packages with the same name.
Ideally, the generated .html files would be in directories that corresponded to the package hierarchy of the original source files. I'm guessing that we can't just fix the -Dd flag (much as ideally we would), since who knows how many projects depend on its current behavior, but a new flag which fixed the behavior would certainly be nice. As it stands, it's a pain to organize the .html files into the package hierarchy so that they don't conflict if there are duplicate module names and so that links can reasonably be generating from ddoc macros.
Alternatively. the generated files could match the full module name, with underscores replacing the slashes in the path (similar to what Phobos does). Personally, I'd prefer just having the package hierarchy retained via directories so that the documentation and source directories are an exact match save for the change in file extensions, but either way, at least we'd have a solution.
Comment #1 by issues.dlang — 2017-12-11T11:32:13Z
Upon further reflection, while in principle, I definitely prefer having folders over using underscores to replace slashes, the underscores solution works a lot better with stuff like css files, since then you don't have to worry about figuring out a way to keep track of where in the package hierarchy you are and thus what the adjusted relative path would be to something like the css directory.
Comment #2 by zan77137 — 2019-09-23T07:27:03Z
LDC has a `-oq` option that solves this.
> -oq - Write object files with fully qualified names
The `-oq` option seems to have been created for object files, but it also seems to have an effect on the HTML output of the document.
This option uses dots instead of slashes for hierarchy.
I think adding this option to dmd will help solve this issue.
Comment #3 by maxsamukha — 2019-10-05T09:04:25Z
(In reply to SHOO from comment #2)
> LDC has a `-oq` option that solves this.
>
> > -oq - Write object files with fully qualified names
>
> The `-oq` option seems to have been created for object files, but it also
> seems to have an effect on the HTML output of the document.
> This option uses dots instead of slashes for hierarchy.
> I think adding this option to dmd will help solve this issue.
But it won't solve the issue for -H? I would rather fix "-op" to use the real module FQNs instead of source paths (now "-op" is pretty useless because it forces you to run dmd in the source dir with the folder hierarchy exactly mirroring the package hierarchy). And -oq would be a useful addition too.
foo.d:
module a.b.foo;
--
dmd -D -H -Dddoc -Hdimport -op whatever/path/to/test.d
would then produce:
doc/a/b/foo.html // reasonable folder structure
import/a/b/foo.di // autoimport would work as expected
dmd -D -Dddoc -oq whatever/path/to/test.d:
doc/a.b.test.html
@ichordev created dlang/dmd pull request #14804 "fix Issue 18062 - ddoc: Generated .html files should retain the package hierarchy " fixing this issue:
- fix Issue 18062 - ddoc: Generated .html files should retain the package hierarchy
Added a command-line option for generating docs with different file structures.
https://github.com/dlang/dmd/pull/14804
Comment #6 by robert.schadek — 2024-12-13T18:55:26Z