Have the images for tutorial and admin docs programatically generated.

[Sarah Boyce]

Noticed in the process of reviewing ​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 ​generate screenshots during our Selenium tests, so it might be a nice idea to have our documentation screenshots generated in a similar way.

All the screenshots in the docs would need generation upon the trigger of a command (i.e. manually via a Makefile or similar).

[Natalia Bidart]

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?

[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 ​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 👍

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

[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.

[Natalia Bidart]

Setting has_patch to start the conversation on the topic, but the ​PR definitely needs improvement.

[GitHub <noreply@…>]

In bcc327aa:

Refs #35380 -- Updated screenshots in admin docs.

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

[Natalia <124304+nessita@…>]

In 3fb3b8a:

[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.

[nessita <124304+nessita@…>]

In a6dde9f:

Refs #35380 -- Updated screenshots in intro docs.

[Natalia <124304+nessita@…>]

In 6a574d7:

[5.1.x] Refs #35380 -- Updated screenshots in intro docs.

Backport of a6dde9fbd545d85f0bc2654f2ebfc6f74f3c4791 from main.

[nessita <124304+nessita@…>]

In fb6050e7:

Refs #35380 -- Updated screenshots in intro docs.

[nessita <124304+nessita@…>]

In 90adba8:

Refs #35380 -- Updated screenshots in admin docs.

[Natalia <124304+nessita@…>]

In e934dcfb:

[5.1.x] Refs #35380 -- Updated screenshots in intro docs.

Backport of fb6050e7845fe1a5fa131708be65ad89a31a2633 from main.

[Natalia <124304+nessita@…>]

In 06fb643:

[5.1.x] Refs #35380 -- Updated screenshots in admin docs.

Backport of 90adba85b29230acfe354bffd82bc0d3a4d63c9d from main.

[Natalia Bidart]

After DjangoCon US 2024, Simon shared a PoC to automatically take screenshots of admin pages for a Django project: ​https://github.com/simonw/django-screenshots/

We should evaluate the project to automatically generate screenshots for the Django docs, though it would add a gew new dependencies (playwright and shot-scraper after a quick inspection).