Header generation broken for specific dunder method

[Eric-Arellano]

documentation/docs/api/qiskit/dev/circuit.mdx

Lines 652 to 654 in c387562

	### array\_\_
	<Function id="array__" name="array__" signature="__array__(dtype=None)">

This should be __array__

[arnaucasau]

The problem with this method is that Sphinx generated the id without the double underscore at the beginning, and our script uses that id to set the header.

<dt class="sig sig-object py" id="array__">

In this case, I think it should be fixed in the qiskit repo, by adding the module's name in front of the method similar to how the rest of the methods of that page are defined. This method is special-cased by setting the module to None here, so one solution is to remove that line and line 843.

The change will also fix a cross-reference to params (line 838) that is currently broken. This will be the output of Sphinx after the fix.

And this will be the new id that will help set the correct header:

<dt class="sig sig-object py" id="qiskit.circuit.array">

What do you think? I can open a PR there if you think it's a good solution. I've been trying different things like escaping the underscores, but it didn't work.

Another solution could be to change our script to use the signature for all headers, but not sure if that's feasible always (I can test it) and it will increase the complexity of the script even more.

[Eric-Arellano]

Great investigation, @arnaucasau! The output would be wrong to call it qiskit.circuit.__array__ because we're talking about a generic under method __array__ that you define on any class. We could do Gate.__array__, but better is simply __array__

What happens if you use .. py:function:: rather than py:method?

Re the broken cross-reference, can that be fixed by using the fully qualified path to Instruction.params?

[arnaucasau]

What happens if you use .. py:function:: rather than py:method?

Nothing changes in that case. It sets the dl class to function, but the id is the same as before 🤔

<dl class="py function">
<dt class="sig sig-object py" id="array__">

Re the broken cross-reference, can that be fixed by using the fully qualified path

Yes, we can fix params by using :attr:~qiskit.circuit.Instruction.params 👍

[Eric-Arellano]

Nothing changes in that case. It sets the dl class to function, but the id is the same as before 🤔

Hm, what about setting the module to builtins or __builtins__? If that doesn't work, can you get it to render as Gate.__array__ - it's fine if that includes the full module path?