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

docs: switch to sphinx-autodoc-typehints #1854

Conversation

aucampia
Copy link
Member

@aucampia aucampia commented Apr 18, 2022

Summary of changes

Currently rdflib is relying on sphinx-autodoc's built in handling for type
hints, this however has some deficiencies as it does not handle stuff
inside if TYPE_CHECKING: and thus only work in cases where there are no
potential for circular dependencies.

This patch changes sphinx to use sphinx-autodoc-typehints instead, the
documentation generated by this plugin looks slightly different but as a
positive it correctly works with things defined inside if TYPE_CHECKING:
guards.

Also:

  • moved the _NamespaceSetString type alias to rdflib._type_checking
    This is so that sphinx-autodoc-typehints recognizes it up, as it
    does not handle type aliases that are defined inside
    if TYPE_CHECKING: guards in imported files.
  • remove sphinx requirements from requirements.dev.txt and
    replaced it with -r docs/sphinx-requirements.txt to reduce redundancy.

Checklist

  • Checked that there aren't other open pull requests for
    the same change.
  • Checked that all tests and type checking passes.
  • Considered granting push permissions to the PR branch,
    so maintainers can fix minor issues and keep your PR up to date.

@aucampia
Copy link
Member Author

Will rebase and publish after merging #1825

@aucampia aucampia force-pushed the iwana-20220418T2309-sphinx_autodoc_typehints branch from 963dee1 to 953aa1b Compare April 19, 2022 07:15
@aucampia aucampia marked this pull request as ready for review April 19, 2022 08:58
@aucampia aucampia force-pushed the iwana-20220418T2309-sphinx_autodoc_typehints branch from 953aa1b to 5ca45ef Compare April 19, 2022 17:32
@aucampia aucampia marked this pull request as draft April 19, 2022 17:34
@aucampia
Copy link
Member Author

marking as draft so I can fix warnings.

@aucampia aucampia force-pushed the iwana-20220418T2309-sphinx_autodoc_typehints branch from 5ca45ef to 6e235bc Compare April 19, 2022 18:32
@aucampia
Copy link
Member Author

Difference illustrated below:

Again, the reason why sphinx-autodoc-typehints is mainly because it also resolves type aliases, and then shows the underlying types instead of the alias name, so if the type hint was _TripleType, and _TripleType = Tuple[Node, Node, Node], then sphinx-autodoc-typehints will put Tuple[Node, Node, Node] in the docs instead of _TripleType. This is primarily so that #1853 does not result in confusing documentation, once this is merged I will rebase that so that the docs can be reviewed with this in place.

@aucampia aucampia marked this pull request as ready for review April 19, 2022 18:49
Currently rdflib is relying on sphinx-autodoc's built in handling for type
hints, this however has some deficiencies as it does not handle stuff
inside `if TYPE_CHECKING:` and thus only work in cases where there are no
potential for circular dependencies.

This patch changes sphinx to use sphinx-autodoc-typehints instead, the
documentation generated by this plugin looks slightly different but as a
positive it correctly works with things defined inside `if TYPE_CHECKING:`
guards.

Also:
- moved the `_NamespaceSetString` type alias to `rdflib._type_checking`
  This is so that `sphinx-autodoc-typehints` recognizes it up, as it
  does not handle type aliases that are defined inside
  `if TYPE_CHECKING:` guards in imported files.
- remove sphinx requirements from requirements.dev.txt and
  replaced it with -r docs/sphinx-requirements.txt to reduce redundancy.
@aucampia aucampia force-pushed the iwana-20220418T2309-sphinx_autodoc_typehints branch from 6e235bc to af93d38 Compare April 19, 2022 20:44
@ghost
Copy link

ghost commented Apr 20, 2022

PR branch looks very nice and closer to what I conceive of as a "typical" programming model, i.e. what one would reference when documenting or authoring HOW-TOs.

Copy link
Member

@nicholascar nicholascar left a comment

Choose a reason for hiding this comment

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

good plug in use!

@nicholascar nicholascar merged commit 7fb9eeb into RDFLib:master Apr 20, 2022
@aucampia aucampia deleted the iwana-20220418T2309-sphinx_autodoc_typehints branch May 7, 2022 09:30
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