feat: Parse sphinx parameter types as Expr expressions#392
Merged
pawamoy merged 5 commits intomkdocstrings:mainfrom Jul 9, 2025
Merged
feat: Parse sphinx parameter types as Expr expressions#392pawamoy merged 5 commits intomkdocstrings:mainfrom
pawamoy merged 5 commits intomkdocstrings:mainfrom
Conversation
Contributor
Author
|
Oh, and on 3.14 there were some tests that acted differently because of the way typing.Union is handled. See https://docs.python.org/3.14/whatsnew/3.14.html#typing |
pawamoy
requested changes
Jul 8, 2025
Member
pawamoy
left a comment
There was a problem hiding this comment.
Looking good, thanks a lot! Just a few nitpicks.
Member
Yep I need to fix that 🙂 |
pawamoy
approved these changes
Jul 9, 2025
Member
pawamoy
left a comment
There was a problem hiding this comment.
Just a few more, let me batch-commit them and we're good to merge 🙂
Member
|
Thank you! 🚀 |
Contributor
Author
There’s other tests (not in the diff) that could have been changed, i limited myself to the scope of the PR |
Member
|
Yep that's good 👍 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR enhances the sphinx docstring style by parsing the type annotations as an expression, when given either with
:param a_type foo:or a:param foo:+:type foo: a_typepair. It uses thedocstrings.utils.parse_docstring_annotation()function, that is also used in the google docstring style parser file.Used on a real project, this means that the parameters types in the table can become cross references or links, event if they aren't coming from the annotations of the function signature. Before this PR, only the typing annotations in the signature render to links.
For example, on a simple mkdocs configuration for the astroid project (the one I want to use mkdocstrings with is too complex to know if problems are caused by us or mkdocstrings), this gives:


Before:
After:



Some tests were added with the expected expression objects, but without the
parent=defined forExprNameobject types, as type checking complains, see #391. I noticed that the assertions usingas_dict()still pass even if the parents are different, so I'm not sure if it is a bug or they are ignored.Please make sure the asserts added at the end are sufficient, and the ones there are needed. I played around a bit when writing them. Please also make sure I correctly used the expressions as intended.
I have another feature/fix queued up related to this, when a
:param a_type foo:has a type that contains spaces (that is not supported by the (upstream) sphinx project either, see), that ended up skipping the parameter in the generated docs, while the info was there. The test added for this helps to cover more cases related to this PR. Because of #391, the test added fails. Since the fix is kinda of another feature, I excluded it from this PR, my first to this repo.