Running `make docs` twice fails to report warnings / generate an error

[bradcray]

When our use of make docs / chpldoc was changed to incrementally rebuild only module documentation that had been changed since its last run, it also sweeps errors under the rug if the files containing the errors are not edited between runs.

As an example:

• introduce an intentional error into one of the chpldoc strings of a documented module
• run make docs—this should break the build with a warning pointing to the error in the doc string
• run make docs again—this time it passes, but shouldn't.

One effect of this is that you can think you have a clean build of the docs on your desktop, only to have it fail once docs are built in a PR's CI process. For example, you only fix some of the errors, not all, rebuild and get a clean report even though the build is not. Another problematic case is when the file where the fixes were implemented gets recompiled, but the file in which the error was actually reported does not.

To fix this, presumably the logic that implements the incremental rebuilds would need to be updated to always recompile files that generate warnings.

[bradcray]

The workaround for this is to cd doc && make clobber before running your next make docs.

[lydia-duncan]

Another work-around is to edit all the files that have errors (but seriously, that's disappointing)

[bradcray]

Another work-around is to edit all the files that have errors (but seriously, that's disappointing)

Meh... How I usually hit this is:

• several screenfulls of errors scroll by, where many/most of them seem to have a common problem
  • there are enough of them that I don't go through and make a list of all files or all errors
• I fix that main problem and re-run make docs, hoping that (as with C errors), fixing some will resolve others
• I get a clean build back, making me think I'm in good shape
• Then I either file the PR or do a make clobber and new errors re-appear

[lydia-duncan]

I had this crop up today when making the channel deprecation - because I hadn't edited the URL module, make docs didn't realize it needed to rebuild that file and so didn't tell me there were errors in it until the clean CI check failed