Building docs when dependencies have ddoc warnings

[Jonathan M Davis]

On Wednesday, April 9, 2025 1:11:35 AM MDT Anonymouse via Digitalmars-d-learn wrote:
> On Tuesday, 8 April 2025 at 14:27:24 UTC, Jonathan M Davis wrote:
> > 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).
>
> Like this, yes?
>
> ```sdl
> configuration "docs" {
>      buildRequirements "allowWarnings"
> }
> ```

You'd have to read the dub documentation. I don't know off the top of my
head, and in my experience, I've typically had to create new configurations
to make changes rather than it working to alter existing ones, but I may
have been doing it wrong.

> This is similar to how I add dflags to `unittest` builds.
>
> If I do this in my `dub.{sdl,json}`, it doesn't carry to
> dependencies, despite `dub build -b docs` being called in my
> project root. It seems like dependencies build individually as
> separate steps, each in their own `configuration "docs"` and/or
> global `buildRequirements`. I have to clone each failing one and
> modify their `dub.json` manually, or in practice fork them if I
> want to build docs (to check for errors) as part of CI.
>
> Is there no other way?

If dub is building any dependencies with the "docs" target when you're
building your own documentation, then that's just bad design. It shouldn't
need to build _any_ of the dependencies to build your documentation, since
there's no linking involved (or shouldn't be). With regards to the
dependencies, nothing beyond importing should be required to build your
documentation, and it shouldn't need to link anything from your project's
dependencies or from the project itself.

If dub is building any dependencies when you try to build the docs target
for your project, then I'd suggest that you create your own separate
configuration just for building your documentation. IIRC, dub lists the
flags for each of its default configurations in its documentation, so you
can just copy that and switch -w to -wi (or just drop the flag entirely).

But as I said, I've never used dub to build documentation, so all I can
really say about how it works would be whatever dub's documentation says.
When using ddoc, I've always built it with a build separate from dub where I
can control what's going on.

- Jonathan M Davis