broken docs since v2 of doc_builder

[BrennanGit]

example: https://github.com/xmos/fwk_voice/actions/runs/3327995023/jobs/5503721918#step:4:668

Issue comes up between sphinx v4.4 and v4.5: https://github.com/sphinx-doc/sphinx/compare/v4.4.0..v4.5.0 Confirmed that pinning every other dependency and only changing the sphinx version repros the effect.

Issue goes away if removing "content-only" from files like "modules/lib_aec/doc/src/reference/header_files.rst" Which does have an effect on the rendering. It should work but if it doesn't, it's not the largest price to pay.

with sphinx 4.4 and content-only

with sphinx 5.2 without content-only

[BrennanGit]

This issue will likely be solved in a later release of sphinx but we have no guarantees when. Our options then are:

• downgrade to sphinx 4.4 in doc_builder and rerelease it
• remove the "content-only" doxygen option and accept the slightly more cluttered appearance

[mbanth]

My 2p worth, remove the "content-only" doxygen option and live with the slightly more cluttered appearance. I choose this option because we know that living with an old version of a 3rd-party tool runs several unplesant risks.

[andrewdewhurst]

I propose we comment out the content-only directive for now. At least this way, it would be simply to un-comment it at somw later date if this functionality is fixed.

[BrennanGit]

Ok the artifacts in the latest develop build look ok to me. They all have the extra page lines from the removed content-only but we have pdfs and html that looks the same.