[Issue 18062] New: ddoc: Generated .html files should retain the package hierarchy

[d-bugmail at puremagic.com]

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 at puremagic.com
          Reporter: issues.dlang at 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.

--