Use meson to generate docs (html + pdf)

[omoerbeek]

Short description

Same script used for rec, auth and dnsdist docs. All meson.build file gain a few new targets: html_docs, html-docs.tar.bz2 and product-name.pdf and a do all called all-docs.

To test run meson compile -C builddir *target*.

Note that generating a pdf needs latex. The meson script does not check for that atm.

TODO:

• generating doc sources(by dnsdist-rust-lib/dnsdist-settings-documentation-generator.py) for dnsdist (see Makefile.am in dnsdist-rust-lib) these file are actually in git, so no need to generate them

Checklist

I have:

• read the CONTRIBUTING.md document
• compiled this code
• tested this code
• included documentation (including possible behaviour changes)
• documented the code
• added or modified regression test(s)
• added or modified unit test(s)
• checked that this code was merged to master

[coveralls]

Pull Request Test Coverage Report for Build 13394452463

Details

• 0 of 0 changed or added relevant lines in 0 files are covered.
• 53 unchanged lines in 12 files lost coverage.
• Overall coverage decreased (-0.002%) to 64.497%

---

Files with Coverage Reduction	New Missed Lines	%
modules/gpgsqlbackend/gpgsqlbackend.cc	1	88.62%
pdns/distributor.hh	2	51.86%
pdns/dnsdistdist/dnsdist-crypto.cc	2	75.72%
pdns/recursordist/rec-tcpout.cc	2	63.49%
pdns/ws-auth.cc	2	80.79%
ext/yahttp/yahttp/url.hpp	3	54.42%
pdns/opensslsigners.cc	3	61.2%
pdns/recursordist/recpacketcache.hh	3	89.55%
pdns/misc.cc	4	62.84%
pdns/recursordist/syncres.cc	6	80.17%

Totals
Change from base Build 13374437384:	-0.002%
Covered Lines:	127623
Relevant Lines:	166873

---

💛 - Coveralls

[eli-schwartz]

This won't be updated when new files are added. The QEMU project faced this challenge already, and wrote a neat trick to solve it:

https://gitlab.com/qemu-project/qemu/-/blob/master/docs/sphinx/depfile.py

This allows you to use depfile: ... and have sphinx report what files it used and which should trigger further rebuilds.

[omoerbeek]

Ah, I mentioned the drawback in the commit message. I'll look into it.

[eli-schwartz]

Yes, Meson isn't a fan of this run_command method... because it's better done by depfiles any time you don't explicitly need the input files as command line arguments! :)

(When you do need them as command-line arguments, for example with executable() sources, I tend to recommend running a generator script as a pre-commit hook, then using fs.read('sources.list').strip().split('\n') instead. fs.read will produce reconfigure dependencies, much like an automake include.)

[eli-schwartz]

Actually, the depfile (sphinx.d) is removed by nija after generating
it as shown by a trace. I do not know why, but touching an .rts
file has the correct behaviour. So I suspoect it is an optimization.

--> ninja -d list

debugging modes:
[...]
  keepdepfile  don't delete depfiles after they're read by ninja

We use depfiles for all *.o outputs as well. Ninja reads them in after the command finishes for build nodes that declare they provide depfiles, and compiles them into a binary database (.ninja_deps) for, as you guessed, optimization purposes. No need to read tons of tiny files in on every startup. :)

Hence also why keeping the file around is one of the options exposed in the debugging modes. Though, I don't know why it is necessary to delete them after reading them, but maybe the ninja authors figured the file is useless after reading it, so might as well compact the build directory size a tiny bit.