Add /@@test-rendering views to docs

[Manas-Kenge]

Issue number

• Fixes Add a mention of the /@@test-rendering views to the developer documentation for Classic UI #1871

Description

This is a WIP, need an initial review to keep working. As per #1871 (comment) a mention of both test-rendering and Storyboard docs in the migration docs under Migrating from Plone Classic UI to Volto is remaining.

---

📚 Documentation preview 📚: https://plone6--1903.org.readthedocs.build/classic-ui/theming/create-add-on.html#styles-test-rendering

[stevepiercy]

I'll do a second review, but for now...

• Please follow https://6.docs.plone.org/contributing/documentation/authors.html#plone-documentation-styleguide, specifically:

  Headings should be "Sentence cased", not "Title Cased".

• Don't inject content between a target (classic-ui-template-slots-label)= and its heading. Keep them close together.

• The correct proper name is "Classic UI" with a space.

• Use 4 spaces indentation in all list items, else they don't render correctly.

• This content breaks flow of the original document. You must consider where it belongs, and not throw it in wherever.

• A picture is worth a thousand words. Screenshots would be nice. See guidance in https://6.docs.plone.org/contributing/documentation/myst-reference.html#images-and-figures

[stevepiercy]

@plone/classicui-team could I get a review from y'all on content accuracy, and where this documentation should reside? It's in the wrong place at the moment. Thank you!

[petschki]

I'd suggest to put this somewhere into classic-ui/theming/create-add-on.md as subsection Styles Test Rendering

[acsr]

@Manas-Kenge Thx for this initial iteration. Maybe we need another round.

[jensens]

It is indeed important information for theming Classic UI.

[acsr]

I am lost how to review latest changes due to confusion if a test build exists or how to checkout the latest state of the pr locally. If I am the origin of that mess, get me out of the ditch… ;-)

[stevepiercy]

@acsr I'm not sure exactly what you want to review, but to see the rendered HTML, visit the pull request preview at https://plone6--1903.org.readthedocs.build/classic-ui/theming/create-add-on.html#styles-test-rendering. If a repo supports pull request previews, then Read the Docs will insert a link in the PR description, which I then usually modify to point to the affected files for convenience.

To checkout this branch, you first need to add a git remote https://github.com/Manas-Kenge/documentation.git, then git fetch --all, and finally checkout the branch. You can then view git commit history.

[acsr]

visit the pull request preview at https://plone6--1903.org.readthedocs.build/classic-ui/theming/create-add-on.html#styles-test-rendering.

I did exactly this (the link at the top of the PR) but it did not work for me. (I had this several times, that these links seem broken. I thought it was due to they were outdated because of changes after a review.)

But it is possible that Github ditches them after some time.

[acsr]

@Manas-Kenge THX! Everything else looks good to me… except the orphaned Colormode switcher hint, that needs more love. I suggest taking it out and continue in a seperate iteration issued by @petschki .

[stevepiercy]

visit the pull request preview at https://plone6--1903.org.readthedocs.build/classic-ui/theming/create-add-on.html#styles-test-rendering.

I did exactly this (the link at the top of the PR) but it did not work for me. (I had this several times, that these links seem broken. I thought it was due to they were outdated because of changes after a review.)

But it is possible that Github ditches them after some time.

RTD inserts the link immediately when it starts the build, not when the build completes. So if you visit the link within 5 minutes of the PR creation, then you might get a 404. Otherwise, it should always work. It works for me now.

[acsr]

LGTM @petschki @Manas-Kenge @stevepiercy finally fine…

[acsr]

Background: I was waiting for over 10 years to have this finally in the docs. There is nothing done unless you do it. (Shame on me). In this case I at least wrote the ticket now. And @Manas-Kenge picked it up.

When Ramon and Albert were working on Barceloneta they were surprised when I showed it to them in Sorrento. But then I left it to others to make it into the docs.

[stevepiercy]

I just noticed that these images are too wide to display clearly in the portal. Please see https://6.docs.plone.org/contributing/documentation/myst-reference.html#width-of-media.

You can either crop out the left toolbar or collapse it.

I also found a bug and opened an issue in plone-sphinx-theme for it, but that's beyond the scope of this PR.

[stevepiercy]

Please resize the browser such that images are no wider than 760 pixels, as described in https://6.docs.plone.org/contributing/documentation/myst-reference.html#width-of-media

[jensens]

There is also for any type with image fields the @@images-test view from plone.namedfile.

[stevepiercy]

There is also for any type with image fields the @@images-test view from plone.namedfile.

https://classic.demo.plone.org/@@images-test 😢

@jensens got a valid link to view?

[jensens]

in theory this should work, but its broken, hmm, smells like a bug
https://classic.demo.plone.org/en/demo/an-image.jpg/@@images-test

[stevepiercy]

in theory this should work, but its broken, hmm, smells like a bug https://classic.demo.plone.org/en/demo/an-image.jpg/@@images-test

And an old one at that plone/plone.namedfile#125.

Until it's resolved, we shouldn't document it.

[stevepiercy]

@mauritsvanrees corrected me, and created a new issue plone/plone.namedfile#173.

[stevepiercy]

You need to resize the browser window, then take the screenshot to fit the browser area that matters. Downsizing an image worsens its legibility. Was that not clear in the documentation?

https://6.docs.plone.org/contributing/documentation/myst-reference.html#width-of-media

[Manas-Kenge]

Hey @stevepiercy, I did as you asked, but the image quality hasn't improved even after taking the screenshots.

[stevepiercy]

You did not resize your browser width. In this screenshot, you can see that I resized my browser width such that the area I want to capture has a width of 760 pixels.

I would then get a screenshot of only that area I needed, without all the navigation.

[stevepiercy]

There we go! Thank you! Merging when green.

[mauritsvanrees]

in theory this should work, but its broken, hmm, smells like a bug https://classic.demo.plone.org/en/demo/an-image.jpg/@@images-test

I have released Plone 6.1.1 final, and Philip has updated the Classic demo site and this now works.