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.
