#35887: Improve Examples for StackedInline and TabularInline
-------------------------------------+-------------------------------------
Reporter: Alexander Lazarević | Owner: Alexander
Type: | Lazarević
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Alexander Lazarević):
> Philosophically, I don't agree that every ModelAdmin example needs to be
complete with `admin.site.register()`.
I personally think the matter is far less philosophical than just
practical.
I didn't touch every example, but the ones that start with an import of
some sort, because this gives, at least me, the impression, that the
example is complete and there are no missing pieces I have to figure out
to get it to work.
> (Why are inlines a special case?)
I would argue that in this case it should be made clear that Inlines don't
need to be registered with Admin but just the ModelAdmin. Neither the
reference nor the tutorial mention this explicitly. You say it's obvious?
Maybe not for everybody. So I think it's better to show that in an
example.
> This is reference documentation, not a how to or tutorial that's meant
to be copy and pasted.
But I think it should be obvious if it is a complete or a partial example.
If we would argue there are only partial examples in the reference
documentation, than why include imports at all? They are not crucial to
the examples and just add additional length as well?
> IMO, we should avoid boilerplate that adds additional length.
I think the benefit of adding one line of `admin.site.register()` to have
a complete example outweighs the benefit of saving that one line by far.
> If we do proceed with this, `@admin.register` might be preferred over.
`admin.site.register()`.
Does Django have a preferences? admin.site.register is mentioned first in
the docs followed by "there is *also* a decorator for registering your
ModelAdmin classes". So I would think the former is the preference?
> On another topic the PR addresses, I agree with updating the examples to
use relative imports, however, I'd advocate for doing it more
comprehensively as in this [https://github.com/django/django/pull/17748
PR]
I focused to improve the examples for the admin and especially the ones
for the Inlines. While doing that I also updated them to use relative
imports, to make it easier to use them without to have to rename `myapp`
in whatever your app's name is.
I'm aware that there might be other examples, that could use relative
imports as well. I could look into this, but would rather keep the scope
of this ticket and the PR on the admin doc and it's examples.
--
Ticket URL: <https://code.djangoproject.com/ticket/35887#comment:5>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion visit
https://groups.google.com/d/msgid/django-updates/0107019300167e08-f4d5f8cb-19f1-4e63-9826-c7e00935d499-000000%40eu-central-1.amazonses.com.
