search

breathe-doc / breathe

ReStructuredText and Sphinx bridge to Doxygen
https://breathe-doc.org
Other
751 stars 199 forks source link

Differences with rendering of param and tparam attributes between versions 4.28 and 4.29 #693

Closed K3WLBUDDY closed 3 years ago

K3WLBUDDY commented 3 years ago

Source doxygen comment:

source_cmt

Output with Breathe 4.28 which seems to be the correct one:

breathe_old

Output with Breathe 4.29 which seems to be borked:

breathe_new

K3WLBUDDY commented 3 years ago

The same issue is observed with param doxygen tags as well with 4.29

vermeeren commented 3 years ago

@K3WLBUDDY If I assume Breathe 4.29.0, then this is probably because of #670. However, in screenshot of #670 you can see it renders differently with proper Template Parameters text.

Can you try latest Breathe and also post Sphinx version or try with newer Sphinx? If that doesn't work, can you add reproduction case?

noname77 commented 3 years ago

hey, i'm experiencing the same issue in the c# domain

starting from 4.29.0, parameters and the return value are printed as a table without the Parameters and Return section headers. additionally, each parameter is prefixed with a Param keyword. the issue is also present in latest master branch of breathe (3023db0) image

sphinx version does not seem to matter with the same rendering for 3.5.4 (highest available for breathe==4.28.0) and 4.1.2 when upgrading sphinx to latest

i've been trying different combinations of sphinx and breathe to try and narrow this down. when installing (downgrading) breathe==4.28.0, sphinx version gets dropped to 3.5.4:

% python -m pip install 'breathe==4.28.0'                              
Collecting breathe==4.28.0
  Using cached breathe-4.28.0-py3-none-any.whl (82 kB)
Requirement already satisfied: six>=1.9 in ./_env/lib/python3.8/site-packages (from breathe==4.28.0) (1.16.0)
Collecting Sphinx<3.6,>=3.0
  Using cached Sphinx-3.5.4-py3-none-any.whl (2.8 MB)
Requirement already satisfied: docutils>=0.12 in ./_env/lib/python3.8/site-packages (from breathe==4.28.0) (0.16)
Requirement already satisfied: setuptools in ./_env/lib/python3.8/site-packages (from Sphinx<3.6,>=3.0->breathe==4.28.0) (56.0.0)
Requirement already satisfied: sphinxcontrib-devhelp in ./_env/lib/python3.8/site-packages (from Sphinx<3.6,>=3.0->breathe==4.28.0) (1.0.2)
Requirement already satisfied: sphinxcontrib-jsmath in ./_env/lib/python3.8/site-packages (from Sphinx<3.6,>=3.0->breathe==4.28.0) (1.0.1)
Requirement already satisfied: sphinxcontrib-htmlhelp in ./_env/lib/python3.8/site-packages (from Sphinx<3.6,>=3.0->breathe==4.28.0) (2.0.0)
Requirement already satisfied: babel>=1.3 in ./_env/lib/python3.8/site-packages (from Sphinx<3.6,>=3.0->breathe==4.28.0) (2.9.1)
Requirement already satisfied: sphinxcontrib-applehelp in ./_env/lib/python3.8/site-packages (from Sphinx<3.6,>=3.0->breathe==4.28.0) (1.0.2)
Requirement already satisfied: snowballstemmer>=1.1 in ./_env/lib/python3.8/site-packages (from Sphinx<3.6,>=3.0->breathe==4.28.0) (2.1.0)
Requirement already satisfied: Jinja2>=2.3 in ./_env/lib/python3.8/site-packages (from Sphinx<3.6,>=3.0->breathe==4.28.0) (3.0.1)
Requirement already satisfied: imagesize in ./_env/lib/python3.8/site-packages (from Sphinx<3.6,>=3.0->breathe==4.28.0) (1.2.0)
Requirement already satisfied: sphinxcontrib-serializinghtml in ./_env/lib/python3.8/site-packages (from Sphinx<3.6,>=3.0->breathe==4.28.0) (1.1.5)
Requirement already satisfied: requests>=2.5.0 in ./_env/lib/python3.8/site-packages (from Sphinx<3.6,>=3.0->breathe==4.28.0) (2.26.0)
Requirement already satisfied: Pygments>=2.0 in ./_env/lib/python3.8/site-packages (from Sphinx<3.6,>=3.0->breathe==4.28.0) (2.10.0)
Requirement already satisfied: alabaster<0.8,>=0.7 in ./_env/lib/python3.8/site-packages (from Sphinx<3.6,>=3.0->breathe==4.28.0) (0.7.12)
Requirement already satisfied: packaging in ./_env/lib/python3.8/site-packages (from Sphinx<3.6,>=3.0->breathe==4.28.0) (21.0)
Requirement already satisfied: sphinxcontrib-qthelp in ./_env/lib/python3.8/site-packages (from Sphinx<3.6,>=3.0->breathe==4.28.0) (1.0.3)
Requirement already satisfied: pytz>=2015.7 in ./_env/lib/python3.8/site-packages (from babel>=1.3->Sphinx<3.6,>=3.0->breathe==4.28.0) (2021.1)
Requirement already satisfied: MarkupSafe>=2.0 in ./_env/lib/python3.8/site-packages (from Jinja2>=2.3->Sphinx<3.6,>=3.0->breathe==4.28.0) (2.0.1)
Requirement already satisfied: certifi>=2017.4.17 in ./_env/lib/python3.8/site-packages (from requests>=2.5.0->Sphinx<3.6,>=3.0->breathe==4.28.0) (2021.5.30)
Requirement already satisfied: urllib3<1.27,>=1.21.1 in ./_env/lib/python3.8/site-packages (from requests>=2.5.0->Sphinx<3.6,>=3.0->breathe==4.28.0) (1.26.6)
Requirement already satisfied: charset-normalizer~=2.0.0 in ./_env/lib/python3.8/site-packages (from requests>=2.5.0->Sphinx<3.6,>=3.0->breathe==4.28.0) (2.0.4)
Requirement already satisfied: idna<4,>=2.5 in ./_env/lib/python3.8/site-packages (from requests>=2.5.0->Sphinx<3.6,>=3.0->breathe==4.28.0) (3.2)
Requirement already satisfied: pyparsing>=2.0.2 in ./_env/lib/python3.8/site-packages (from packaging->Sphinx<3.6,>=3.0->breathe==4.28.0) (2.4.7)
Installing collected packages: Sphinx, breathe
  Attempting uninstall: Sphinx
    Found existing installation: Sphinx 4.1.2
    Uninstalling Sphinx-4.1.2:
      Successfully uninstalled Sphinx-4.1.2
  Attempting uninstall: breathe
    Found existing installation: breathe 4.30.0
    Uninstalling breathe-4.30.0:
      Successfully uninstalled breathe-4.30.0
Successfully installed Sphinx-3.5.4 breathe-4.28.0

% python -m pip freeze
[...]
docutils==0.16
Sphinx==3.5.4
sphinx-csharp==0.1.11
sphinx-rtd-theme==0.5.2
sphinxcontrib-applehelp==1.0.2
sphinxcontrib-devhelp==1.0.2
sphinxcontrib-htmlhelp==2.0.0
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==1.0.3
sphinxcontrib-serializinghtml==1.1.5
sphinxcontrib-versioning==2.2.1

with that the output is rendered as expected with proper section headers and nicely formatted params (note the inline keyword still present before it was fixed) image

if i force upgrade to latest sphinx, docutils and even sphinx-rtd-theme afterwards, the render is still the same as above (so fine despite dependency mismatch / error), so it seems its just the bump to breathe>4.28.0 that causes the issue

% python -m pip install docutils sphinx sphinx-rtd-theme --upgrade
[...]
Installing collected packages: docutils, sphinx
  Attempting uninstall: docutils
    Found existing installation: docutils 0.16
    Uninstalling docutils-0.16:
      Successfully uninstalled docutils-0.16
  Attempting uninstall: sphinx
    Found existing installation: Sphinx 3.5.4
    Uninstalling Sphinx-3.5.4:
      Successfully uninstalled Sphinx-3.5.4
ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.
breathe 4.28.0 requires Sphinx<3.6,>=3.0, but you have sphinx 4.1.2 which is incompatible.
Successfully installed docutils-0.17.1 sphinx-4.1.2

% pip freeze
breathe==4.28.0
docutils==0.17.1
Sphinx==4.1.2
sphinx-rtd-theme==1.0.0rc2

i'd be happy to provide more information / testing if necessary

thanks, wiktor

jakobandersen commented 3 years ago

This new rendering is intentional as it uses the underlying Sphinx machinery instead of custom Breathe functionality. See also #708. In short, in your theme it should be possible to add CSS to change the appearance of the field lists to get something very close to the old style. But if some extra markup is needed please reopen.