Support setting argument/return types in the docstring

[thebigmunch]

Not everybody uses (or wants to use) type hints in their code. Not supporting setting types in the docstrings limits the user base of mkdocstrings to those that do.

Would you be amenable to adding support for setting the types in the docstring? It would probably make most sense to follow the Google style as done with sections.

Thanks for the consideration and the promising package.

[pawamoy]

I don't really want to add support for types in docstrings. Here is why:

• as usual, added complexity, work, maintenance work. If someone is willing to be responsible for its support, then why not, but I myself do not volunteer 🙂
• I consider that, if you need comprehensive documentation of your Python code, you probably need type annotations anyway, to ensure quality of your code. It's totally subjective of course, and I have no problem with people thinking otherwise
• I think type annotations is a good addition to ensure quality of a project, and thus am trying to promote it. You know, being opinionated.
• Google-style sections are valuable to me because, contrary to :param: and the likes, they help keeping the docstring readable in the Python interpreter, with the help builtin. But types in these same docstrings are now kinda replaced, in a better way, by type annotations (well, I guess having the type written next to the param name helps readability as well, so this point might not stand...)

However. I know type annotations are still not widely used. It's starting, but a lot of projects are still not using them. As you correctly said, not supporting types in docstrings limits the user base of mkdocstrings (though I'm not targetting every project. mkdocstrings is particularly focused on modern/recent projects, for which it's easy to add type annotations).

Therefore, maybe we could add support for types in docstrings, for those who are transitioning to type annotations, but still, I am not sure about the value of that.

Lets leave that issue open and wait for feedback / upvotes.

P.S.: if anyone wonders, type hints in comments (# type: int) are a big no.

[thebigmunch]

Type annotations actively decrease readability of code. For people that are familiar with them, they might increase the understandability of the code. But they are mainly for static analysis tools. I, for one, will never use them in my hobby code. I write that code specifically to be as accessible to novices as possible. Type annotations very much go in the opposite direction.

While you might think it is best for projects to have them, there are many good reasons Python core devs responsible for them said they shouldn't be required as far as Python itself is concerned.

My projects are quite modern and recent. I'm an early adopter of many things. And I kinda resent the implication that a valid choice to not use type annotations makes them otherwise. Moreover, type annotations are simply not required for comprehensive documentation. Again, the implication is a bit insulting to us that choose not to use them.

I am perfectly fine if you choose not to work on it or even choose to not have it in at all. But, many of your reasons are invalid, incorrect, and/or insulting.

[pawamoy]

many of your reasons are invalid, incorrect, and/or insulting.

It was not meant to be insulting, sorry if my wording offended you (I am also not a native english speaker, so my tone might be off).

Obviously, I should have asked about your use-cases.

I want this project to be welcoming for contributors, and I made the same mistake that drove me away from other projects (learning time!).

As I said, the reasons I mentioned are only my opinion, and I'm far from knowing everything or having experienced it all, so indeed, they might be incorrect. Thank you for expressing yours.

Let's say this is not my priority, and PRs are welcome (though you might want to wait a bit for me to comment the code because it's not pretty).

[thebigmunch]

I didn't take any intent from it. But your bias was shining through very clearly. Obviously you are enthusiastic about type annotations and want them to become more prevalent. But you have to be careful not to turn that into thinking or expressing that those don't use the thing you like are less than. They have certain uses that are valuable in certain situations; they are certainly valuable at my day job (software consulting). But much of the Python ecosystem doesn't really benefit them. And even if they might, they have to learn their purpose, syntax, and tooling before they might even become useful to them. And then that is one more thing to maintain. And another thing to try to teach anyone who might want to contribute to your project (else you have to add them to PRs yourself). Python is also a language often taught/learned as a first language. Along with them not being required for Python or the CPython codebase, these reasons will always limit the usage of type annotations in the Python ecosystem.

[pawamoy]

You're right, and I agree.

I am enthusiastic about type annotations. It was never my intention to say that those who don't are incorrect, and I especially do not think that way, please understand that.

Put shortly, I tried to justify my unwillingness to add support for something I wanted to drop in my own projects, when I should have just stopped to that: I'm unwilling to do so.

Maybe I'm not so unwilling anymore though. You made valid points. Once the code is a bit more stable and robust, I'll see how this could be handled.

[thebigmunch]

Put shortly, I tried to justify my unwillingness to add support for something I wanted to drop in my own projects, when I should have just stopped to that: I'm unwilling to do so.

Indeed. Though it's hard to tell with a stranger, if you had just said something like "I prefer to use type annotations for my projects, and I'm not willing to support something myself other than that.", I would have just said "Ok, thanks for the consideration." and moved on. I've been on both sides of that exchange many times in my life; it's no big deal. I'd have probably waited until the codebase was more stable to fork, modify, and maintain my own copy that supports what I needed. It wouldn't be much work for me as this feature seems to be the only box not ticked for me. I'm in the process of doing something similar with automatic code formatting : )

Either way, I'm looking forward to seeing what the future holds for this project.

[shyamd]

One way to deal with this might be to make an Abstract docstring class and have multiple implementations that can be selected by a parameter to mkdocs.

[pawamoy]

Yes. Once mkdocstrings is configurable (globally and per "autodoc" instruction), we'll have to find elegant ways of dealing with these options in both the selection of objects and their rendering. If you have any experience with that, please share :slightly_smiling_face:

[thebigmunch]

As pointed out in https://github.com/pawamoy/mkdocstrings/issues/32#issuecomment-576891229, there is a docstring parsing package that might make take care of some of the work.

[pawamoy]

Hey @thebigmunch, I'll transfer this issue over to pytkdocs since it's now the project that is responsible for loading Python documentation, including docstrings :slightly_smiling_face:

[thebigmunch]

I'll transfer this issue over to pytkdocs since it's now the project that is responsible for loading Python documentation, including docstrings

Well, this issue was about mkdocstrings supporting this; doesn't really belong in the tracker for the module created with the lower-level functionality to add that support to mkdocstrings. In my eyes, it should stay on the mkdocstrings tracker and be closed when mkdocstrings has the ability to do this. Just because py-tkdocs adds support for it doesn't mean mkdocstrings gets that support, at least not right away. But it's your call.

[pawamoy]

pytkdocs and mkdocstrings roadmaps stay tightly coupled. With the upcoming release of mkdocstrings it'll be easy to update it with new pytkdocs features.

If it's a question of issue visibility, feel free to open an issue on mkdocstrings linking back to this one, but I think discussion about this feature request should happen on this repo.

Organizing issues also helps me deal with them!

[thebigmunch]

Well, this issue topic is implicitly expected from a docstring parser, so it doesn't really make sense to be here. And, if the solution is to open the same issue back up on mkdocstrings, that seems to say that is where this issue should have stayed. Then if you think it needed to be here as well, you could open an issue here linked back to it. All the discussion in this issue pertains to mkdocstrings, not py-tkdocs.

[pawamoy]

Well, this issue topic is implicitly expected from a docstring parser.

No it's not, because I never signed anything saying I must support all styles in docstrings. Even more, this projet is not a docstring parser. It's a documentation-tree/object-tree retriever/loader. It happens to also parse docstrings because it was the most straight forward way to bring better support for them in mkdocstrings. In the contributing issue of mkdocstrings, I listed a "proper Google-style docstring markdown extension" as something that could really beneficiate mkdocstrings. This markdown extension would be the docstring parser.

so it doesn't really make sense to be here

So the issue about parsing docstring makes no sense in the project which parses them? You're asking for a particular style to be supported (not speaking about it's popularity or use), so I think it makes total sense.

if the solution is to open the same issue back up on mkdocstrings, that seems to say that is where this issue should have stayed.

A solution to what? This debate?

Then if you think it needed to be here as well, you could open an issue here linked back to it.

Yes I could have done that, but I didn't. Should we move forward or continue arguing? In your previous comment, you said "it's your call", so I'm invoking that.

Now, just so you know, if we implement this feature here, it should immediately be available in mkdocstrings, transparently, because of how we build data here and render it there. So you don't have to worry about that.

---

I feel like I'm going down a dangerous road with you, replying in this manner (bullet point), and that this conversation could never end. I'm trying my best to do the free, volunteer work of developing Python projects, because I love it, and I can feel insulted as well sometimes. I hope we can agree to put aside the details of issue management and work toward the goal of implementing the feature.

[pawamoy]

@thebigmunch could you try the latest release of mkdocstrings (v0.10.0)? I added support for type hints in docstrings. I'd like to know if this is working for you. I'll close this issue, open new ones if you encounter any issues.