Django is really powerful. It has magic no other framework has.
However, due to the dynamic nature of Python, features aren’t obvious.
Developers don’t know what features a class has unless they dig through the convoluted source code themselves or going online to check the documentation.
For example when implementing a forms.ModelForm hovering over it in an IDE reveals absolutely nothing useful.
Additionally, the documentation pages for django are not easy to use at all.
Compared to other frameworks especially, the docs are bad.
There are so many docs generators out there that generate bountiful docs, it would be a shame not to take advantage.
What do the “Django Lords” have to say about inlining the documentation in the source code itself.
This would provide an easy to use generated site and great IDE docs.
Thanks!
2 Likes
yes, i validate +1. especially if we can have a detailed documentation of django under the bonnet. it would be a great value added for new contributor.
This would also require adding some stub files.
Adding documentation to Meta would require a stub.
I know the “Django Lords” have been weary of adding type stubs.
However adding a docstring to this
class Model(models.Model):
...
class Meta: <<<<<
...
would require some stubs/.pyi files.
I wouldn’t want to work on this just to find out that there are benefits of the current setup. And that they aren’t willing to make a tradeoff.
What would be the best way of asking the Django Governing Board about their opinion on n this?
You’ve taken the first step by posting the idea here.
As documented at Requesting features, you may also wish to express your idea on the developer’s mailing list as well.
Be aware that this is not a fast process. We are all volunteers and it takes time for people to see the post, give it the thought that it deserves, form a thoughtful opinion, and provide an appropriate response.
1 Like
