sphinx 4.1.0 problems with parsing template keywords

[agoscinski]

Quickfix would be to be enforce the sphinx version (4.0.2) for the moment, but maybe this can be easily fixed.

From https://app.circleci.com/pipelines/github/cosmo-epfl/librascal/2609/workflows/bb24e509-0294-4b5f-bdd0-93d00ff63f91/jobs/22550 the error

Exception occurred:
  File "/usr/local/lib/python3.6/dist-packages/sphinx/util/cfamily.py", line 275, in fail
    raise self._make_multi_error(errors, '')
sphinx.util.cfamily.DefinitionError: Invalid C++ declaration: Expected identifier in nested name, got keyword: template [error at 8]
  template< class > class

[Luthaf]

Are you sure this is due to Sphinx 4.1.0? I.e. did you reproduce the issue locally, or changed the version used in CI to fix this?

[max-veit]

I can confirm that downgrading Sphinx from v4.1.0 to v4.0.1 (and changing nothing else) fixes the doc build. I think we should report the issue to the Sphinx developers -- as the error message suggests -- and then pin the Sphinx version in our CI, because this is the second time a random Sphinx update has broken our build.

[Luthaf]

I reported with a small reproducing example in https://github.com/sphinx-doc/sphinx/issues/9477, it seems that the latest sphinx version fails to parse "advanced" template usage (parameter packs and higher order template parameters). Until they have a fix, we can pin sphinx to 4.0.1 in CI!

[Luthaf]

The error actually comes from breathe (the doxygen => sphinx adapter), and are PR to fix it (follow the link in the sphinx issue to find it). Unfortunately, breathe is a bit understaffed and the review might take a while, so for now moving back to sphinx 4.0 might be the best solution.