[Django] #35380: Have the images from docs/ref/contrib/admin/_images/ automatically generated.

[Django]

#35380: Have the images from docs/ref/contrib/admin/_images/ automatically
generated.
------------------------------------------------+------------------------
Reporter: Sarah Boyce | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Uncategorized | Version: dev
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
------------------------------------------------+------------------------
Noticed in the process of reviewing
[https://github.com/django/django/pull/17910/ this PR] that there was an
image in the documentation that required an update.
I think most of the images are "slightly" out of date due to in part to
the accessibility push which has done some css contrast updates.

We already have the ability to
[https://docs.djangoproject.com/en/dev/internals/contributing/writing-code
/unit-tests/#running-the-selenium-tests generate screenshots] during our
Selenium tests, so it might be a nice idea to have our documentation
screenshots generated in a similar way.
--
Ticket URL: <https://code.djangoproject.com/ticket/35380>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#35380: Have the images from docs/ref/contrib/admin/_images/ automatically
generated.

--------------------------------------+------------------------------------

Reporter: Sarah Boyce | Owner: nobody
Type: Cleanup/optimization | Status: new

Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

--------------------------------------+------------------------------------
Changes (by Natalia Bidart):

* component: Uncategorized => Documentation
* stage: Unreviewed => Accepted

Comment:

Accepting because I agree that outdated images in docs are confusing. I
have some questions though:

Do you think that the effort to put the machinery in place (despite
already having the screenshot generation by code) is worth the effort vs
asking for a PR that touches the admin to re-generate these screenshots?
(I'm honestly not sure!)

If we would automatically generate these images, when/where would this
regeneration go? As part of a release when building and checking release
notes? As part of the same PR that changes something in the admin? As a
follow up PR?
--
Ticket URL: <https://code.djangoproject.com/ticket/35380#comment:1>

[Django]

#35380: Have the images from docs/ref/contrib/admin/_images/ automatically
generated.
--------------------------------------+------------------------------------
Reporter: Sarah Boyce | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------

Comment (by Sarah Boyce):

> (despite already having the screenshot generation by code)

Unless I am missing something, these screenshots are not generated
automatically and in order to update the image, I had to:
- look at the image (and the docs around it) and figure out what I would
need to do to recreate this image
- make a project [https://docs.djangoproject.com/en/5.0/intro/contributing
/#creating-projects-with-a-local-copy-of-django using steps documented
here]
- do steps to recreate the image - code/migrate/shell etc
- take a screenshot

I'm not sure if that answers the question. There are other approached to
make this easier like having a project already setup with test data with
some instructions.

> asking for a PR that touches the admin to re-generate these screenshots

I think we can ask that people do this. I would expect we update the
contributor docs with how to update the images whether that's a script or
a project they can use or something something.

> If we would automatically generate these images, when/where would this
regeneration go? As part of a release when building and checking release
notes? As part of the same PR that changes something in the admin? As a
follow up PR?

Ideally part of the same PR that change something in the admin but we
should also check it as part of a release when building and checking
release notes 👍
--
Ticket URL: <https://code.djangoproject.com/ticket/35380#comment:2>

[Django]

#35380: Have the images from docs/ref/contrib/admin/_images/ automatically
generated.
--------------------------------------+------------------------------------
Reporter: Sarah Boyce | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------

Comment (by Natalia Bidart):

Thank you Sarah, I agree with your rationale! we could perhaps consider a
custom Sphinx extension to build the images if certain conditions are met?
--
Ticket URL: <https://code.djangoproject.com/ticket/35380#comment:3>

[Django]

#35380: Have the images from docs/ref/contrib/admin/_images/ automatically
generated.
--------------------------------------+------------------------------------
Reporter: Sarah Boyce | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------

Comment (by Tim Graham):

I think it would be enough to double check if the the screenshots need
updating once for each major release (probably at alpha stage). Certainly
if there are obvious UI changes that affect the screenshots they could be
updated as part of each change, but I wouldn't require it for each CSS
tweak. It's unlikely beginners are going to be using the development
version of Django for the tutorial anyway. I don't think this problem
merits spending a lot of time on building automation. Outdated screenshots
hasn't been a big issue over the years.
--
Ticket URL: <https://code.djangoproject.com/ticket/35380#comment:4>

[Django]

#35380: Have the images from docs/ref/contrib/admin/_images/ automatically
generated.
--------------------------------------+------------------------------------
Reporter: Sarah Boyce | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1

Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------

Changes (by Natalia Bidart):

* has_patch: 0 => 1
* needs_better_patch: 0 => 1

Comment:

Setting has_patch to start the conversation on the topic, but the
[https://github.com/django/django/pull/18211 PR] definitely needs
improvement.
--
Ticket URL: <https://code.djangoproject.com/ticket/35380#comment:5>

[Django]

#35380: Have the images from docs/ref/contrib/admin/_images/ automatically
generated.
--------------------------------------+------------------------------------
Reporter: Sarah Boyce | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------

Comment (by GitHub <noreply@…>):

In [changeset:"bcc327aa326093a39f01a9bc98198807444900f3" bcc327aa]:
{{{#!CommitTicketReference repository=""
revision="bcc327aa326093a39f01a9bc98198807444900f3"
Refs #35380 -- Updated screenshots in admin docs.

When listing users, ensure that user first and last name are diverse.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/35380#comment:6>

[Django]

#35380: Have the images from docs/ref/contrib/admin/_images/ automatically
generated.
--------------------------------------+------------------------------------
Reporter: Sarah Boyce | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------

Comment (by Natalia <124304+nessita@…>):

In [changeset:"3fb3b8a4fd13f7fa13c31872a0582d948d51d5a3" 3fb3b8a]:
{{{#!CommitTicketReference repository=""
revision="3fb3b8a4fd13f7fa13c31872a0582d948d51d5a3"
[5.1.x] Refs #35380 -- Updated screenshots in admin docs.

When listing users, ensure that user first and last name are diverse.

Backport of bcc327aa326093a39f01a9bc98198807444900f3 from main.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/35380#comment:7>

[Django]

#35380: Have the images from docs/ref/contrib/admin/_images/ automatically
generated.
--------------------------------------+------------------------------------
Reporter: Sarah Boyce | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------

Comment (by nessita <124304+nessita@…>):

In [changeset:"a6dde9fbd545d85f0bc2654f2ebfc6f74f3c4791" a6dde9f]:
{{{#!CommitTicketReference repository=""
revision="a6dde9fbd545d85f0bc2654f2ebfc6f74f3c4791"
Refs #35380 -- Updated screenshots in intro docs.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/35380#comment:8>

[Django]

#35380: Have the images from docs/ref/contrib/admin/_images/ automatically
generated.
--------------------------------------+------------------------------------
Reporter: Sarah Boyce | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------

Comment (by Natalia <124304+nessita@…>):

In [changeset:"6a574d7f830a573e73363f3cb671c34ef9150e85" 6a574d7]:
{{{#!CommitTicketReference repository=""
revision="6a574d7f830a573e73363f3cb671c34ef9150e85"
[5.1.x] Refs #35380 -- Updated screenshots in intro docs.

Backport of a6dde9fbd545d85f0bc2654f2ebfc6f74f3c4791 from main.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/35380#comment:9>