Skip to content

Temporarily disable typehints and singledispatch in function signatures #606

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

Merged
merged 2 commits into from
May 9, 2022

Conversation

IvanIsCoding
Copy link
Collaborator

@IvanIsCoding IvanIsCoding commented May 7, 2022

Closes #504

Temporarily disables the typehints and single dispatch in functions signatures until Qiskit/qiskit_sphinx_theme#21 is fixed.

Currently, the hints only appear on the functions with single dispatch and only appear for the graph argument. Because we already document that those functions accept both PyGraph and PyDiGraph, I argue that we do not lose much by disabling the hints.

Here is what the documentation looks like after the PR is applied:

Captura de tela de 2022-05-07 09-32-24

@coveralls
Copy link

coveralls commented May 7, 2022

Pull Request Test Coverage Report for Build 2286936931

  • 0 of 0 changed or added relevant lines in 0 files are covered.
  • No unchanged relevant lines lost coverage.
  • Overall coverage remained the same at 97.175%

Totals Coverage Status
Change from base Build 2283131205: 0.0%
Covered Lines: 11626
Relevant Lines: 11964

💛 - Coveralls

Copy link
Collaborator

@georgios-ts georgios-ts left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks nice! It's an easy and quick fix. I agree we don't lose any information by dropping the type hints.

If we're going down this path, we could also leverage autodoc-before-process-signature and unregister PyGraph, PyDiGraph from the single dispatch functions when building the docs. https://stackoverflow.com/questions/25951651/unregister-for-singledispatch. In this way we'll avoid the repetition of the signatures.

@IvanIsCoding
Copy link
Collaborator Author

Looks nice! It's an easy and quick fix. I agree we don't lose any information by dropping the type hints.

If we're going down this path, we could also leverage autodoc-before-process-signature and unregister PyGraph, PyDiGraph from the single dispatch functions when building the docs. https://stackoverflow.com/questions/25951651/unregister-for-singledispatch. In this way we'll avoid the repetition of the signatures.

I tried unregistering but it makes the docs fail because we still need to use some of the methods in jupyter-execute.

I also tried using autodoc-process-signature to filter the signatures and I ended up with the normal signature and two blank signatures, it did not filter out the signatures unfortunately.

I pushed a trick that should be harmless to the code and tricks Sphinx. It is 100% implementation dependant on this check from Sphinx, but it gets the job done.

Let me know what you think of the trick. The documentation now looks like this:

Captura de tela de 2022-05-07 09-32-24

@IvanIsCoding IvanIsCoding changed the title Temporarily disable typehints in function signatures Temporarily disable typehints and singledispatch in function signatures May 7, 2022
Copy link
Collaborator

@georgios-ts georgios-ts left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good! It's a bit hacky but it works :)

@georgios-ts georgios-ts added the automerge Queue a approved PR for merging label May 9, 2022
@mergify mergify bot merged commit a64d69a into Qiskit:main May 9, 2022
@IvanIsCoding IvanIsCoding deleted the fix-obscure-signature branch June 4, 2022 19:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
automerge Queue a approved PR for merging documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[joss] Function signatures are obscured in the documentation
3 participants