Data parameter from Operator class does not show properly in API reference

[Guillermo-Mijares-Vilarino]

Environment

• Qiskit Terra version: N/A
• Python version: N/A
• Operating system: N/A

What is happening?

The part of the Operator class API reference page from qiskit.quantum_info in which the parameters are listed does not show properly. In particular, where the data argument is supposed to be the page reads:

Parameters
or (data (QuantumCircuit) – Instruction or BaseOperator or matrix): data to initialize operator.

Instead of

Parameters
data (QuantumCircuit or Instruction or BaseOperator or matrix): data to initialize operator.

However I don't see any problem with the source code:

def __init__(self, data, input_dims=None, output_dims=None):
        """Initialize an operator object.

        Args:
            data (QuantumCircuit or
                  Instruction or
                  BaseOperator or
                  matrix): data to initialize operator.
            input_dims (tuple): the input subsystem dimensions.
                                [Default: None]
            output_dims (tuple): the output subsystem dimensions.
                                 [Default: None]

How can we reproduce the issue?

• Open the Operator class API reference page.
• Check the parameters section

What should happen?

You should see the aforementioned error.

Any suggestions?

No response

[ikkoham]

Thank you for finding the bug!

[dalin27]

As a follow up, could there be an issue with how the docstring is formatted? I am not very familiar with how the docstring is parsed using Napoleon (a Sphinx extension), but maybe the colon should be on the same line as data!? Maybe something like this:

Args:
      data (QuantumCircuit or Operation or BaseOperator or matrix): 
                          data to initialize operator.
      input_dims (tuple): the input subsystem dimensions.
                          [Default: None]
      output_dims (tuple): the output subsystem dimensions.
                           [Default: None]

Note also that due to some recent update in the operator.py file, the correct line that should appear in the API reference page is

data (QuantumCircuit or Operation or BaseOperator or matrix): data to initialize operator.

That is, Instruction has been replaced by Operation.

[jakelishman]

@dalin27: yeah, I would expect that Sphinx's parser is probably choking because it's not finding the colon. Putting it on one line should help out.

The online documentation still says Instruction because the online documentation is for Terra 0.21.2, and the Operation interface is only on the main branch, and planned to be released in Terra 0.22. We're not planning to release a 0.21.3 patch (unless something super critical happens very soon), so any documentation fix would go out with 0.22.