feat: Parse sphinx parameter types as Expr expressions#392
feat: Parse sphinx parameter types as Expr expressions#392pawamoy merged 5 commits intomkdocstrings:mainfrom
Conversation
|
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
left a comment
There was a problem hiding this comment.
Looking good, thanks a lot! Just a few nitpicks.
Yep I need to fix that 🙂 |
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 🙂
|
Thank you! 🚀 |
There’s other tests (not in the diff) that could have been changed, i limited myself to the scope of the PR |
|
Yep that's good 👍 |
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.