can DDOC generate files names including the full path ?

[Jonathan M Davis]

On Wednesday, August 14, 2019 3:43:10 AM MDT wjoe via Digitalmars-d-learn 
wrote:
> For example if the source tree looks like this:
> >source/
> >
> >   foo/
> >
> >      baz.d
> >
> >   bar/
> >
> >      baz.d
>
> and generating the docs with something like this:
> >  dmd -D -Dd=docs foo/baz.d bar/baz.d
>
> the output looks like this:
> >docs/
> >
> >  baz.html
>
> one baz overwrites the other.
>
> I'd like to have something like this:
> >docs/
> >
> >    foo.baz.html
> >    bar.baz.html
>
> There's the  -op  flag, but that litters the source tree with
> html files.
> Neither the docs https://dlang.org/spec/ddoc.html nor google
>
> Also there's more annoying behavior:
>
> - Documentation generation fails if  -version  s are not provided
> resulting in a rather long command and it's tedious to manually
> keep track of it. Is there a way to make it only honor
> version(none) and treat all other -version s as a given ?
>
> - if the  -o-  isn't provided, dmd complains about missing
> symbols. Why ? -D enables documentation mode, doesn't it?

For better or worse, a documentation build is basically just a normal build
except that the version identifier D_Ddoc is declared, and the documentation
is generated. There are people who actually generate documentation as part
of their normal build. Personally, I don't think that that's a good approach
in general, because sometimes, you need to declare a version block that's
just for documentation and as such won't actually work (e.g. a declaration
for a symbol which is different on each platform would often require a
separate version just for the documentation where that version has the
documentation and a declaration but no actually definition). In order to
allow people to build with -D as part of their normal build and have it
work, Phobos actually has its own version identifier that it declares for
its documentation build instead of relying on D_Ddoc, since if it used
D_Ddoc, pretty much no one could build their documentation as part of their
normal build.

In any case, because a documentation build is basically normal build, it
certainly isn't the case that you can have all of the version identifiers
declared, and you're going to get complaints about missing symbols if stuff
is missing. Also, the compiler doesn't really have a good way built in to
deal with directories when generating documentation. It wants to shove
everything in the same directory and just use the module name (not the
package) when picking the names for the html files, which can be
problematic.

Realistically, what you tend to need to do if you actually want some control
over how files are named is to compile each file individually with -o- and
using -o to specify the actual file name you want with the appropriate path.

Alternatively, you can use other documentation generators. dub comes with
ddox built in, or you can use Adam Ruppe's adrdox:

https://github.com/adamdruppe/adrdox

The built-in documentation generation can work quite well, but it's not
quite as plug-and-play as would be nice and does tend to require that you
put together a build script to generate your documentation instead of just
being able to pass a single command and have it all just work.

- Jonathan M Davis