Use breathe>=4.27 to support Doxygen \page, \section, etc.

[mwtoews]

This PR removes two hacks that I think are no longer needed.

The big one is to use recent breathe features, mainly breathe-doc/breathe#635 which is part of version 4.27

With the rendered output, the layout of cpp_general for both html and pdf is generally improved, but with more structured headers. Cross-references to node names in this section also work as expected.

The second removed hack is to not follow the bug workaround for Doxygen 1.8.17, and to just throw an error instead. This is partly because the need for a tmp_breathe directory (used for the breathe hack) was removed.

[mwtoews]

Hmm, with a new container update, a new issue emerges from make spelling:

...
Encoding error:
'ascii' codec can't encode character '\u201c' in position 39: ordinal not in range(128)
The full traceback has been saved in /tmp/sphinx-err-cab77k47.log, if you want to report the issue to the developers.
make: *** [spelling] Error 2
Makefile:43: recipe for target 'spelling' failed

I'm unable to replicate this locally. Also note that python3 -c "print('\u201c')" returns “.

[rouault]

I'm unable to replicate this locally

even within the updated container ?

[rouault]

Note: I had tagged the previous version of the container as osgeo/proj-docs:2020

[mwtoews]

even within the updated container ?

Ok, I am now getting the error with osgeo/proj-docs:latest. However, I'm unable to get the error on my Ubuntu laptop in a fresh venv or conda environment via pip. I'll need to investigate this further ....

[rouault]

Restarting the Docs job with the updated Docker image

[mwtoews]

Cherry-picked into 8.0, so now you can see the new layout in this section, or page 429 of the current PDF.

[hobu]

Is there a way with breathe to suppress index entity creation nowadays? It makes a sloppy mess of the indexes, and I think our indexes would be better off with a few manual entries pointing to the beginning of the API section rather than the auto-generated entries which take up a bunch of space and add little.

[mwtoews]

Is there a way with breathe to suppress index entity creation nowadays?

You mean in the PDF version? Yes I agree, and will take a look to try and suppress this generation.