Building docs when dependencies have ddoc warnings

[Jonathan M Davis]

On Sunday, April 6, 2025 9:30:31 AM MDT Anonymouse via Digitalmars-d-learn wrote:
> I'm using `dub build -b docs` as a way to detect when I did ddoc
> wrong, such as mismatching `Params` sections and actual parameter
> names.
>
> Sadly one of the dependencies I (indirectly) use already *has*
> incorrect ddoc, and it prevents me from building my own docs as
> it halts the process.
>
> ```
> $ dub build -b docs
>      Starting Performing "docs" build using /usr/bin/dmd for
> x86_64.
>      Building arsd-official:characterencodings 10.9.10 [library]
>      Building arsd-official:dom 10.9.10 [library]
>      Building mir-core 1.7.1 [library]
>      Building mir-algorithm 3.22.3 [default]
> ../../../home/zorael/.dub/packages/mir-algorithm/3.22.3/mir-algorithm/source/mir/interpolate/constant.d(275,6): Warning: Ddoc: function declaration has no parameter 'grid'
> ../../../home/zorael/.dub/packages/mir-algorithm/3.22.3/mir-algorithm/source/mir/polynomial.d(93,1): Warning: Ddoc: function declaration has no parameter 'F'
> ../../../home/zorael/.dub/packages/mir-algorithm/3.22.3/mir-algorithm/source/mir/string_map.d(35,1): Warning: Ddoc: function declaration has no parameter 'U'
> Error: warnings are treated as errors
>         Use -wi if you wish to treat warnings only as
> informational.
> Error /usr/bin/dmd failed with exit code 1.
> ```
>
> What can I do here? dub doesn't seem to have a `-wi` equivalent
> and I don't see a way to pass it on to dmd. The immediate idea to
> do `DFLAGS=-wi dub build -b docs` just gives the same results.

I would assume that you need to create a similar build config which doesn't
use -w (though really, -w should be gotten rid of, because it causes a
variety of problems, and thanks to how code introspection works, it can
actually affect how your code compiles). From what, I've seen, that's
typically what you need to do when you want to change the flags for a dub
build. It _might_ be possible to redefine one of the standard build configs
- in this case, docs - but I don't think that I've succeeded when I've tried
that in the past (though I haven't tried recently).

That being said, personally, I didn't even realize that dub had any sort of
ddoc build (or if I knew, I forgot). I always just set up a separate program
to do it, since as powerful as ddoc is, unless you put in some extra work,
it's probably not going to look like you'd like (not to mention, in some
cases, it's just plain useful to create additional macros). I have no clue
how dub would deal with .dd files (i.e. ddoc files) in addition to .d files,
and that's what you need in some cases. But maybe it all handles it nicely
and makes things easier than using dmd directly. I don't know, since I
haven't messed around with it.

In my case, I created https://github.com/jmdavis/dxml/blob/master/gendocs.d
to do the documentation build for the projects I put on my website, and I
put in in each of my projects, though I haven't needed to change it in
years, so I don't know how easy to follow it is, and some of it may be more
complicated just to get things the way that I wanted on my site.

Of course, none of that is required if you just want to use the standard
macros and let things look however they look by default, but from what I
recall, my experience with that is poor. What I have I took from Phobos and
dlang.org and tweaked for my needs. ddoc is great once you put some effort
into getting it set up, but before that, the experience isn't great - though
it may be good enough depending on what you're trying to do, and the dub
docs build configuration may make it more pleasant if you can get it
working.

- Jonathan M Davis