Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update references to Terra's classes in docstrings #474

Closed
adekusar-drl opened this issue Sep 23, 2022 · 12 comments
Closed

Update references to Terra's classes in docstrings #474

adekusar-drl opened this issue Sep 23, 2022 · 12 comments
Assignees
Labels
good first issue Good for newcomers type: documentation 📖 Issues related to documentation type: enhancement ✨ Features or aspects to improve

Comments

@adekusar-drl
Copy link
Collaborator

What is the expected enhancement?

Review all docstrings in the package and update references to Terra's classes. For instance, in the VQC documentation we reference ``ZZFeatureMap`` that is in qiskit.circuit.library. When the package documentation is generated, the reference becomes just a plain text. Such references should be replaced with cross references, that are replaced in the generated documentations with corresponding links. In this example, in the documentation ``ZZFeatureMap`` to be replaced with `:class:`~qiskit.circuit.library.ZZFeatureMap`. Then in the html documentation this cross reference will become a link to the corresponding class in Terra.

@adekusar-drl adekusar-drl added good first issue Good for newcomers type: enhancement ✨ Features or aspects to improve type: documentation 📖 Issues related to documentation labels Sep 23, 2022
@adekusar-drl adekusar-drl reopened this Jan 11, 2023
@AbdullahKazi500
Copy link

@adekusar-drl Can you explain what is to be done here in HTML Documentation

@adekusar-drl
Copy link
Collaborator Author

The point is to update docstrings across the module in a way that references to classes/methods/etc become clickable in the HTML documentation. For example, in the QuantumKernel source code it is written:

feature_map: Parameterized circuit to be used as the feature map. If None is given,
    the `ZZFeatureMap` is used with two qubits.

In the html documentation available here ZZFeatureMap is highlighted, but it is a clickable link. To make it clickable the text should formatted as :class:`~qiskit.circuit.library.ZZFeatureMap`. Same should be done in other references across the module.

@AbdullahKazi500
Copy link

For example, to create a clickable link to the ZZFeatureMap class in the qiskit.circuit.library module, you would format the text in your docstring as follows right
If None is given, the :class:`~qiskit.circuit.library.ZZFeatureMap` is used with two qubits

@adekusar-drl
Copy link
Collaborator Author

Yes, this is correct.

@AbdullahKazi500
Copy link

I Guess I Can try to work on this 3 issues The SVR and this one while waiting for Terra release

@adekusar-drl
Copy link
Collaborator Author

Ok, I assigned this issue to you as well. But if you don't have time to work on any of them, let me know.

@AbdullahKazi500
Copy link

Yes I will try to and keep you updated

@adekusar-drl
Copy link
Collaborator Author

@AbdullahKazi500 is there any progress here?

@AbdullahKazi500
Copy link

Hi @adekusar-drl I am working to Replace the existing plain text reference with the cross-reference format in each docstring.
and to Generate the package documentation to ensure the cross-referencing works correctly. definitely I will make a pull request soon no need to worry : )

@SamD-1998
Copy link

Is there something else that is yet to be completed in this issue?

@adekusar-drl
Copy link
Collaborator Author

Considering the lack of progress and the time passed since the last message, I think, it is an issue that anybody can give a try.

@woodsp-ibm
Copy link
Member

Closed as done by #700

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
good first issue Good for newcomers type: documentation 📖 Issues related to documentation type: enhancement ✨ Features or aspects to improve
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants