www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - Building docs when dependencies have ddoc warnings

reply Anonymouse <zorael gmail.com> writes:
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/interpolat
/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.
Apr 06
parent reply Jonathan M Davis <newsgroup.d jmdavisprog.com> writes:
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/interpolat
/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
Apr 08
parent reply Anonymouse <zorael gmail.com> writes:
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"
}
```

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?
Apr 09
parent Jonathan M Davis <newsgroup.d jmdavisprog.com> writes:
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
Apr 12