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

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