|Posted by Jonathan M Davis|
in reply to wjoe
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:
> > 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:
> > baz.html
> one baz overwrites the other.
> I'd like to have something like this:
> > 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:
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