More robust documentation checks in CI

[jngrad]

The Sphinx and Doxygen documentations keep piling up errors again. These issues are trivial to fix in the PRs where they emerge in the first place, whereas fixing them weeks after a merge involves a fair amount of guesswork (which can go wrong, as explained in the last meeting with the #2623 case) and has the potential to cause merge conflicts in other opened PRs. CI already fails when Sphinx warnings are raised, to some extent. We should make it more robust and do the same for Doxygen.

• Sphinx: the -W option turns warnings into errors in the check_sphinx container, so issues are difficult to introduce. Unfortunately, some syntax errors are silently ignored by Sphinx. For example, a link to a non-existing Python function won't generate a warning:

  :meth:`espresso.electrostatics.P3M.Tune`

  There are currently several such examples in the documentation. Sometimes it's just a typo, sometimes the function moved and the paragraph must be updated accordingly. These errors can be spotted with a regex on the HTML output because Sphinx doesn't use line wrapping.
• Doxygen: warnings aren't turned into errors, so the check_doxygen container can't fail. Some warnings are not caused by the code and can be filtered out with a regex. dot warnings can probably be removed with a command in the Doxyfile. Some errors are silently ignored, though:

  /** @brief Some function
   *  @return Number of neighbors.
   *  @param p  First particle
   *  @param dist
   *  Detailed explanation of the algorithm.
   */
   void foo(Particle &p, double dist);

  Here the second param has no description, which can be used as a trick to silence a warning about undocumented parameters, because Doxygen will automatically use the subsequent paragraph Detailed ... as the description for parameter dist. This behavior can be unpredictable: if paragraph Detailed... starts with any Doxygen command for paragraph-level markup, the second parameter description remains empty. This error can be spotted with a regex. The superfluous @return will raise a warning in a future release of Doxygen.