Hi Moshe, Just so you know there are a lot more discussions about Django these days on the Django Forum <https://forum.djangoproject.com/> than this mailing list. There are also no such things as Django lords or a governing board :) The project is consensus-driven, so doesn’t require any specific seal of approval.
As a Django beginner I’d really like better support for IDEs with those "hover" features you mentioned – and I don’t see why we’d have to move the docs inline to do that. Why not add docstrings where they’re missing, in addition to the docs as they stand currently? Django is a big enough project that there’s room to provide docs in different ways for different needs, and it doesn’t change often enough that keeping docs in sync would be an issue. According to the Django Developers Survey in 2022 <https://lp.jetbrains.com/django-developer-survey-2022/>, 80% of Django devs use an IDE that offers this "inline docs on hover" developer experience nicety. Django does have plenty of docstrings like this already, so perhaps we can add concise ones where there’s none currently in the public API, rather than having a big documentation refactoring project. Something like this – would be a quick win to add a one-liner for ModelForm: [image: modelform hover screenshot.png] Cheers, Thibaud On Thursday 11 January 2024 at 17:32:28 UTC Jörg Breitbart wrote: > I agree that the official Python docs are well maintained and achieve a > tough goal - the right balance of just replaying basic interface facts > on one side, or being overly prosaic on the other side. Nope, they are > well balanced giving enough of both extremes to get you going, place > repo code lookup links, and examples where needed. > > And Python properly fills the __doc__ attribute on almost every function > or class, which is a big relief in interactive testing sessions to > quickly grasp a rarely used detail not in your muscle memory. > > With Django thats mostly not possible, inspecting __doc__ or using > help(XY) does often not reveal any useful information. > > > So no, I'd be a strong -1 to any recommendation suggesting that > > docstrings be used to clutter up the code. > > I dont see how informative docstrings can clutter code, they are > visually well separated from code bodies, and most editors ven allow to > fold them. > > The bigger issue I see with docstrings is, that they sometimes end up > being written too machine firendly, e.g. full of restructuredText > formatting, which hinders human reading to some degree, esp. if you > never used those formats yourself before. > -- You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group. To unsubscribe from this group and stop receiving emails from it, send an email to django-developers+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/babf5ef5-3269-4799-bbbe-8f2599d1bd8en%40googlegroups.com.
