Transition Docs to Inline

[Moshe Dicker]

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 reveals 
absolutely nothing useful.

[image: image]
image1000×157 11.5 KB


What do the “Django Lords” have to say about inlining the documentation in 
the source code itself.

I know the “Django Lords” have been weary of adding type stubs.
However adding a docstring to this
```
class Model(models.Model):
...
class Meta: < THIS
...
```

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 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 this?

-- 
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/d5ed6671-b8bb-4ce7-b3b8-15b2dd6796a9n%40googlegroups.com.

Re: Transition Docs to Inline

[Moshe Dicker]

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 raises the developer 
experience.
For those with a Visual IDE it’s shown on hover, and even for those with a 
text editor they could see that docstring if they “click-into” the 
class/function/argument/parameter.

What sort of documentation would be inlined?

I will try to explain below how I think the separation of API Reference and 
Guides should be done.

Would this require a large amount of duplication between docs and source 
code?

God Forbid! Sphinx has autodoc which convert doctrings to reStructuredText. 

Why does adding docstrings require pyi files?

It isn’t required but it would help. I imagine that with some stub magic it 
would be possible to get docstrings applied onto a Meta class that doesn’t 
actually inherit anything
class CustomUser(models.Model): class Meta: 
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< verbose_name = _("user") 

Are there other projects that use the approach you suggest?

Pretty much everything else.
Some mix docstrings and handwritten docs into 1 really nice API reference

   - FastAPI - API Reference (docs 
   <https://fastapi.tiangolo.com/reference/uploadfile/#fastapi.UploadFile>|
   code 
   
<https://github.com/tiangolo/fastapi/blob/040ad986d48bb9a400de804f7f25abb856d85e1a/fastapi/datastructures.py#L30>)
 
   

Others write a regular guide separately, but generate API reference from 
docstrings

   - Flask - API Reference (docs 
   <https://flask.palletsprojects.com/en/3.0.x/api/#application-object>|code 
   
<https://github.com/pallets/flask/blob/c2f65dd1cfff0672b902fd5b30815f0b4137214c/src/flask/app.py#L76>
   ) 
   - Pydantic - API Reference (docs 
   <https://docs.pydantic.dev/latest/api/base_model/#pydantic.BaseModel>|
   code 
   
<https://github.com/pydantic/pydantic/blob/e4fa099d5adde70acc80238ff810c87a5cec7ebf/pydantic/main.py#L61>
   ) 

I could go on and on, but I’ve never come across a package that does not 
utilize docstrings at all.

Thanks!
​
On Friday, January 5, 2024 at 11:02:59 AM UTC-5 Tim Graham wrote:

> 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 duplication between docs and source code?
>
> Why does adding docstrings require pyi files? My text editor doesn't have 
> this "hover" feature. Please elaborate on your proposal for the 
> uninitiated. Are there other projects that use the approach you suggest?
> On Wednesday, January 3, 2024 at 2:38:02 PM UTC-5 Moshe Dicker wrote:
>
>> 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 
>> reveals absolutely nothing useful.
>>
>> [image: image]
>> image1000×157 11.5 KB
>>
>> <https://global.discourse-cdn.com/business7/uploads/djangoproject/original/3X/d/f/df1eda85d38f5ff5978a7b966e2e4341bd45138a.png>
>>
>> What do the “Django Lords” have to say about inlining the documentation 
>> in the source code itself.
>>
>> I know the “Django Lords” have been weary of adding type stubs.
>> However adding a docstring to this
>> ```
>> class Model(models.Model):
>> ...
>> class Meta: <<<<< THIS
>> ...
>> ```
>>
>> 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 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 this?
>>
>

-- 
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/368ebda7-d776-4166-83de-9effa42fdb71n%40googlegroups.com.

Re: Transition Docs to Inline

[Moshe Dicker]

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 
   separate really robust API Reference that sources the technical info from 
   the docstrings. 
   Example: This 
   
,
 
   should be in the docstring of null.
   Implementation:class Foo: def __init__(self, value) -> None: """The Foo 
   class. :param value: "Simple string value" :type value: str """ 
   self.value = value foo = Foo(value="bar") 
   2. If this is rejected for whatever reason, can we please add just 
   docstring to link to the online docs.class Foo: def __init__(self, value) 
   -> None: """https://example.com"""; self.value = value foo = Foo(value=
   "bar") 

​

I'm coming from Flutter where the documentation is pretty much only inline 
docs, It's really a pleasure to never need to lookup documentation.

This is a bunch of work. But having a lower barrier to entry is important. 
I think a docs refresh will really rock!

-- 
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/28393ec6-fb8c-4c3c-8f2a-55b56002ee42n%40googlegroups.com.

Re: Transition Docs to Inline

[Moshe Dicker]

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).
But almost all the documentation in ref is connected to a class, function, 
method etc. This can be pushed into the source code and autodoced quite 
easily.
Anything that can’t be in a class can stay the way it is. Correct me if I’m 
wrong, It is almost certain that I am.
(Adding inline docs to django-stubs would help mitigate this, but 
coordinating documentation between 2 different projects would be a 
nightmare.)

I only see 2 downsides to my proposal:

   1. A big refactor to the codebase, There will be strings everywhere. 
   2. A larger install size.

​
On Sunday, January 7, 2024 at 8:53:44 PM UTC-5 Jörg Breitbart wrote:

> +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, if that an easy task to accomplish 
> without bigger refactoring. Django uses a lot of bootstrap/runtime 
> patching under the hood, from custom metaclasses, explicit injection 
> pattern up to proxies at various ends. Currently IDEs often give up 
> here, idk if more inline docs alone can change much or if the level of 
> abstraction within django would have to change to get a significant 
> improvement.
>
> 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/6c56c8b8-0521-42e7-a7fd-98d66ea3c79en%40googlegroups.com.

Re: Transition Docs to Inline

[Moshe Dicker]

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:

> 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 into making Django 
> documentation as great as it is today. It's one of our biggest advantages.
>
> Best,
> Mariusz
>

-- 
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/ad6d6c73-4271-47b3-8aef-40988671fd15n%40googlegroups.com.