Re: Transition Docs to Inline

Hi Moshe, Just so you know there are a lot more discussions about Django these days on the Django Forum 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 specif

Re: Transition Docs to Inline

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 lo

Re: Transition Docs to Inline

On 1/11/2024 12:01 AM, Moshe Dicker wrote: I should not that I'm only being critical to improve. The docs are well written, it's just disorganized. Something I've learned over the past 47 years of reading computer documentation is that _no_ documentation is "perfect" - especially not for ever

Re: Transition Docs to Inline

I should not that I'm only being critical to improve. The docs are well written, it's just disorganized. I mean no disrespect, we stand on the shoulders of giant, but that doesn't mean we should stop trying to improve. On Wednesday, January 10, 2024 at 11:57:40 PM UTC-5 Mariusz Felisiak wrote: >

Re: Transition Docs to Inline

Agreed with Tim. > *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.* This is a really unfair opinion (not the only one in your comment). Hundreds of folks have put a lot of effort in

Re: Transition Docs to Inline

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 sepa

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, w

Re: Transition Docs to Inline

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, w

Re: Transition Docs to Inline

Django uses a lot of bootstrap/runtime patching under the hood, from custom metaclasses, explicit injection pattern up to proxies at various ends. I understand this is true on low level APIs and on classes we implement ourselves (Like passing the correct arguments when creating a django model)

Re: Transition Docs to Inline

+1 on the idea for better inline docs, would be some relief for IDEs figuring out a proper interface story boosting dev speed for rarely used aspects, where currently one would have to search through the prosaic online docs or end up browsing the django source. On the other hand I am not sure,

Re: Transition Docs to Inline

Django’s API Reference is more like a guide than an actual Reference at this point. I’m proposing as follows: 1. We take any part of the reference that is short and to the point and put it in a docstring. I think going the FastAPI route on this would be best, A guide and a separa

Re: Transition Docs to Inline

I will address each part of your questions. Why is consulting the online documentation insufficient? I think most developers build Django projects while referencing the online documentation rather than while reading Django’s source code. Having documentation available within the IDE really r

Re: Transition Docs to Inline

Hi Moshe, Why is consulting the online documentation insufficient? I think most developers build Django projects while referencing the online documentation rather than while reading Django's source code. What sort of documentation would be inlined? Would this require a large amount of duplica