I don't think moving docs inline is a good idea. Quoting Aymeric from 2013 regarding django.contrib.admindocs [1] summarizes my feelings: """ 1) It's called the "documentation generator", but it only operates on docstrings. This promotes the idea that docstrings are appropriate documentation, while the Python and Django communities now favor prose documentation.
2) Even though it's possible to use docstrings to generate API documentation, for instance with Sphinx' autodoc, I find that heavily formatted, Javadoc-style docstrings (or late epydoc-style) tend to be hard to read for humans and I don't want Django to encourage them. """ [1] https://groups.google.com/g/django-developers/c/0-qFyCPuSRs/m/kny7Oeu2RdoJ On Monday, January 8, 2024 at 11:55:19 AM UTC-5 Jörg Breitbart wrote: > Ah interesting that you mentioned django-stubs. I had good to mediocre > success applying it to my own django apps. It gets the job mostly done > for high level interfaces, but shows rough stub edges as soon as you > have to touch lower interfaces (can only speak for the ORM section in > this regard, which is highly mutating itself). > > Type annotations in Python are heavily inspired by Typescript, where > you'd strive for building up you interface types granularily and the > compiler does the rest pulling things together. > I am not sure if Python's type annotations are yet or will ever be > capable to achieve that good enough for most common python paradigm, > seems Python is way too flexible for static type analysis. Typescript > partially solves this by banning/hiding some of JS' flexibility. (Ever > tried to fully type a mutating decorator in Python? Hours of fun ahead, > and you will still end up declaring many Anys effectively disabling > proper type pulling.) > > Now back to Django - it makes heavy usage of dynamic python features, > which is poison for any static type deduction. This is also the reason > why IDEs typically fail for more dynamic python code like django, unless > they do a partial runtime inspection (I think IntelliJ tries to do that > to some degree). > > So while better typing support is really nice where possible, I'd > suggest to not open this can of worms (yet), but mainly to stick to the > better inline docs idea. > > > Cheers, > Jörg > -- 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/011ce3a2-3936-4e90-b205-5d12b229d536n%40googlegroups.com.
