Codecov Report

Merging #2545 into master will increase coverage by 0.01%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master    #2545      +/-   ##
==========================================
+ Coverage   86.12%   86.13%   +0.01%     
==========================================
  Files         526      526              
  Lines       36003    35977      -26     
==========================================
- Hits        31007    30989      -18     
+ Misses       4996     4988       -8

what about renaming EXAMPLE_DOC_EXTRA_TARGETS to EXAMPLE_DOC_TEST_TARGETS?

what about renaming EXAMPLE_DOC_EXTRA_TARGETS to EXAMPLE_DOC_TEST_TARGETS?

Both/all of them also run tests, it is just that some produce output (images), while others do not.
With produced output CMake will not re-run them, but the others are added as explicit targets that get used with make ldoc.
I will rebase / fix this further after #2548.

Reworked it:

• make check-examples runs the tests now always.
• make will generate output files only once, and does not run the examples that do not generate any output. The output from check-examples is used/valid for it, i.e. after make check-examples output files are not regenerated.

@Elv13 on IRC:

the example do modify the doc, they need to be executed

You mean the ones not generating images still need to run when generating docs? Makes sense.
Then we need some stamp file to not run this always. Couldn't/shouldn't that be the changed doc file then?

@blueyed I think we need to add check-examples to the DEPENDS of ldoc if we are to make this change? I don't have time to test right now

@Elv13
check-examples is meant to test it only (but generates output also).
ldoc depends (or should if not) on generate-examples.

There is 3 steps, I think.

• Check what the documentation example provides (text, image, etc)
• Execute those files and generate the artifacts
• Integrate/inject those artifacts in the ldoc input

The images are simple because they are statically deterministic, but the generated text may change when step2 is performed, so it must be executed before CMake configure_file is executed.

This could be mitigated by moving ldoc and the configure_file to a custom_target instead of directly in the configuration step. That way most targets would use the raw .lua files from awful/wibox/gears instead of the post-processed output of configure_file. By doing that the weird circular target dependency would be gone.

make ldoc on master runs e.g. tests/examples/text/awful/keygrabber/root_keybindings.lua always.
But changing the file does not change any documentation.

So while it gets run always, it does not update lib/awful/keygrabber.lua for
ldoc (which replaces the
@DOC_text_awful_keygrabber_root_keybindings_EXAMPLE@).

Therefore I think this PR does not cause any regression in this regard.

Would like to get this in for #2672, to ease handling the examples tests therein / from there.

make ldoc on master runs e.g. tests/examples/text/awful/keygrabber/root_keybindings.lua always.
But changing the file does not change any documentation.

That's a bug, the keygrabbing.lua target should DEPENDS on tests/example/text/awful/keygrabber/* and tests/example/awful/keygrabber/* (if, of course, they exist). That in turn should re-run ldoc. But right, this is not a bug in this pull request.