search

sphinx-contrib / matlabdomain

A Sphinx extension for documenting Matlab code
Other
64 stars 45 forks source link

non-functional :func: and :class: references with identical section name #246

Open rdzman opened 5 months ago

rdzman commented 5 months ago

I have stumbled across a very strange bug with certain :func: and :class: references not working. That is, references like ...

:func:`myfunction`
:class:`myclass`

... will display correctly, but will not render as a functioning link under certain circumstances ... which I think I have finally tracked down to something helpful. The following conditions must hold ...

  1. The name of the class or function must be a single word without underscores.
  2. It must not belong to a package (e.g. mypackage+).
  3. The module name must be . OR you must have matlab_short_links = True.
  4. You must have a section title in the .rst source with the same name as the function or class. I believe this must be in the same .rst file as the corresponding .. autofunction:: or .. autoclass::.

For me, the last two are always satisfied, since I use matlab_short_links = True and I document all of my functions/classes with an .rst stub file that looks something like ...

.. currentmodule:: mymodule

myfunction
----------

.. autofunction:: myfunction

That section title here is critical for my table of contents. It took me a long time to encounter this issue since almost all of my functions/classes are either (1) in a package, or (2) have an underscore in the name.

While I do not have a fix for this issue, I did notice that the conditional in ... https://github.com/sphinx-contrib/matlabdomain/blob/481134f80be0c84ba1a7c17347d3aefc7a82716d/sphinxcontrib/matlab.py#L280 ... evaluates to false for a name without an underscore and to true for a name with an underscore, since the corresponding section name in self.state.document.ids has dashes instead of underscores.

I have a hunch that this may be related to #243, in which case my "fix" in #245 probably isn't the right one.

rdzman commented 5 months ago

Here's a minimal working example ...

matlabdomain-bug-246.zip

rdzman commented 5 months ago

Upon further experimentation, it seems that completely deleting the following lines of code ...

https://github.com/sphinx-contrib/matlabdomain/blob/481134f80be0c84ba1a7c17347d3aefc7a82716d/sphinxcontrib/matlab.py#L261-L267

... solves #243 and it solves this issue for the case where you have matlab_short_links = True (the case that really matters to me), but not the case where the module name is . (as in the case attached above).

I think the only effect of this change is that it will always use the fully qualified name instead of the short name for the HTML anchor tags. Is there any other effect? And if so, wouldn't this be a good idea?

rdzman commented 3 months ago

For clarification, deleting the code in my previous comment is not the right solution. It causes lots of other issues. And nothing in #245 addresses it.

So this issue is still awaiting a solution.

joeced commented 3 months ago

Thanks for the update. I'll try to get time to look at the issue more in depth. However, time is limited at the moment.