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

Enable showing typehints in sphinx function/method signature and content #1728

Merged

Conversation

aucampia
Copy link
Member

Enable showing typehints in sphinx function/method signature and content

With current config sphinx only adds type hints to method/function
signatures.

This patch changes the autodoc_typehints from the default of
signature to both, which is described by sphinx documentation as:
"Show typehints in the signature and as content of the function or method".

For more info see:
https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_typehints

Other changes:

  • Harmonize sphinx version restriction across different places where
    dependencies are defined.
  • Sort requirements files.

With current config sphinx only adds type hints to method/function
signatures.

This patch changes the `autodoc_typehints` from the default of
`signature` to `both`, which is described by sphinx documentation as:
"Show typehints in the signature and as content of the function or method".

For more info see:
https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_typehints
@aucampia
Copy link
Member Author

I compared various options for type hints and sphinx, they can be compared against docs generated current master as of writing this:

image

sphinx-autodoc-annotation

https://aucampia.github.io/pages-raw/Aenei9iu/rdflib.sphinx_autodoc_annotation/apidocs/rdflib.html#rdflib.term.bind

image

sphinx-autodoc-typehints

https://aucampia.github.io/pages-raw/Aenei9iu/rdflib.sphinx_autodoc_typehints/apidocs/rdflib.html#rdflib.term.bind

image

autodoc_typehints="both"

https://aucampia.github.io/pages-raw/Aenei9iu/rdflib.sphinx_adthb/apidocs/rdflib.html#rdflib.term.bind

image

Conclusion

To me the best option seems to be autodoc_typehints="both", as this retains the annotations in the signatures and adds them in the documentation body, integrating them with other docstrings.

sphinx-autodoc-annotation seems to not use some types, and also the type docs it makes are not hyperlinked.

sphinx-autodoc-typehints has somewhat better output than autodoc_typehints="both" in some select situations, but there is no way to retain the types in signatures.

Feedback welcome though.

@aucampia aucampia merged commit 1fdf40c into RDFLib:master Mar 14, 2022
@aucampia aucampia deleted the iwana-20220226T2130-autodoc_typehints_both branch April 9, 2022 14:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants