I'll argue that right now we don't have documentation. We just have a mix of docs and reference, resulting in a convoluted manual that doesn't fit either need. Django isn't some fly-by-night framework whose documentation will devolve if we move the technical reference and documentation into separate parts. Looking at other packages for inspiration, fastapi and pydantic do great work of describing the technical parts and have a manual in a separate section.
Personally I would suggest moving the entire docs to mkdocs, with its better navigation. Although I understand that older frameworks are hesitant to change. I'll argue that right now we don't have documentation. We just have a mix of docs and reference, resulting in a convoluted manual that doesn't fit either need. Django isn't some fly-by-night framework whose documentation will devolve if we move the technical reference and documentation into separate parts. Looking at other packages for inspiration, fastapi and pydantic do great work of describing the technical parts and have a manual in a separate section. Personally I would suggest moving the entire docs to mkdocs, with its better navigation. Although I understand that older frameworks are hesitant to change. --------------------------------From: Tim GrahamDate: Wed, Jan 10, 2024 5:41 PMTo: Django developers (Contributions to Django itself);Cc: Subject:Re: Transition Docs to Inline 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/kny7Oeu2RdoJOn 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. -- 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/3l9as7b7scm3ihdkm38hg0m4.1704927306906%40email.lge.com.
