| |
 | Posted by Jonathan M Davis in reply to Anonymouse | Permalink Reply |
|
Jonathan M Davis 
Posted in reply to Anonymouse
| 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
|