https://issues.dlang.org/show_bug.cgi?id=18062

          Issue ID: 18062
           Summary: ddoc: Generated .html files should retain the package
                    hierarchy
           Product: D
           Version: D2
          Hardware: All
                OS: All
            Status: NEW
          Severity: enhancement
          Priority: P1
         Component: dmd
          Assignee: nobody@puremagic.com
          Reporter: issues.dlang@jmdavisProg.com

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.

--