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

[rdzman]

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 ...

matlabdomain/sphinxcontrib/matlab.py

Line 280 in 481134f

if fullname_out not in self.state.document.ids:

... 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]

Here's a minimal working example ...

matlabdomain-bug-246.zip

[rdzman]

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

matlabdomain/sphinxcontrib/matlab.py

Lines 261 to 267 in 481134f

	if self.env.config.matlab_short_links:
	# modname is only used for package names
	# - "target.+package" => "package"
	# - "target" => ""
	parts = modname.split(".")
	parts = [part for part in parts if part.startswith("+")]
	modname = ".".join(parts)

... 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]

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]

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.