Document ImageRenditionField's filter spec

[berzi]

Currently, ImageRenditionField is not documented at all, it's only mentioned in one place plus changelogs with the apparent expectation that the reader already knows what to write in its filter_spec argument, except the latter is also not documented anywhere and only mentioned in changelogs.

I would submit a PR directly, but from the code alone I can only get a fragmented idea of what is supported, and I'm not (yet) an expert in Wagtail nor am I familiar with its internals yet.

Pertinent section of the Wagtail docs

https://github.com/wagtail/wagtail/tree/main/docs/reference

I think a reference entry would be appropriate and a user would look for the content there. I also propose a directory reference/fields where both ImageRenditionField and the existing StreamField documents could go together.

Details

• [ ] The allowed syntaxes for filter_spec (with | separators, with separators),
• [ ] the parts of filter_spec strings (<SOME STRING><HYPHEN><DIMENSIONS>),
• [ ] the allowed operations (the first part of the filter_spec string),
• [ ] the subset of operations that are valid for SVGs,
• [ ] the preserve_svg flag and what happens when it's True (i.e. operations that aren't valid of SVGs are disregarded even for non-SVGs),
• [ ] that the supported operations can be expanded with custom ones, and how

should all be clearly documented.

I find it especially challenging to find conclusive information on the allowed operations and how to expand them. If someone can provide exhaustive information on that, I can take care of writing the whole thing.

[zerolab]

@berzi a quick note on filter_spec - this is the image operations specification which can be transform filters (e.g. resize. docs) or simple filter operations (e.g. image quality or output format) and any custom defined filters

filter_spec allows one or more operations to be performed on the image, and they are separated by |.

The best way to fully understand filters is to follow the code - https://github.com/wagtail/wagtail/blob/2b061ac96e5ffdad2759e39bfdbca0fc242ae854/wagtail/images/models.py#L831

preserve_svg is used to narrow down operations ("filters") to those safe to SVGs, and in case of ImageRenditionField applies only if the image is an SVG - https://github.com/wagtail/wagtail/blob/2b061ac96e5ffdad2759e39bfdbca0fc242ae854/wagtail/images/utils.py#L120-L128

IMHO, https://docs.wagtail.org/en/stable/advanced_topics/api/v2/configuration.html#images-in-the-api is mostly there and 80% of the work is to link to the various other areas of the documentation.

[phatwillis]

Issue Summary: The ImageRenditionField in Wagtail is not currently documented, and its usage, especially the filter_spec argument, is not clear. This issue proposes documenting the ImageRenditionField with a focus on the filter_spec argument and related functionalities.

Pertinent Section of the Wagtail Docs: Reference Section

Proposed Changes: Documentation Location:

Create a new directory reference/fields in the Wagtail documentation. Place the documentation for both ImageRenditionField and existing StreamField together for better organization. Documentation Content:

Document ImageRenditionField comprehensively, focusing on the filter_spec argument. Cover the allowed syntaxes for filter_spec with | separators and without separators. Explain the components of filter_spec strings, such as . Outline the allowed operations, providing clarity on each operation's purpose. Specify the subset of operations that are valid for SVGs. Document the preserve_svg flag and its impact when set to True. Provide information on how to expand the supported operations with custom ones. Research Tasks:

Review the code for ImageRenditionField to understand its functionality. Research the allowed syntaxes for filter_spec and the structure of filter_spec strings. Investigate the allowed operations and subset of operations for SVGs. Understand the preserve_svg flag and its functionality. Explore how to expand the supported operations with custom ones. Documentation Draft:

Draft the documentation with clear examples and use cases. Include details on each aspect mentioned in the proposed changes. Pull Request Submission:

Submit a pull request with the comprehensive documentation changes. Ensure that the new documentation aligns with the overall structure and style of the existing content. Conclusion: By addressing this documentation issue, users will have a clear and comprehensive resource for understanding and utilizing the ImageRenditionField in Wagtail, particularly focusing on the intricacies of the filter_spec argument and related functionalities. (Source: ChatGpt.)

[zerolab]

@phatwillis please do not post ChatGPT rubbish that does not add any value to the discussion

[phatwillis]

Thank You alot, I'm really sorry for that.

On Fri, 29 Dec 2023, 10:11 pm Dan Braghiș, @.***> wrote:

@phatwillis https://github.com/phatwillis please do not post ChatGPT rubbish that does not add any value to the discussion

— Reply to this email directly, view it on GitHub https://github.com/wagtail/wagtail/issues/11398#issuecomment-1872339597, or unsubscribe https://github.com/notifications/unsubscribe-auth/AOC5ITCQU7ECBT6FYACDKHLYL4WYNAVCNFSM6AAAAABBEEHFZKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQNZSGMZTSNJZG4 . You are receiving this because you were mentioned.Message ID: @.***>

[anshikavashistha]

@berzi may i work on this issue?

[berzi]

@anshikavashistha Sure, you're welcome to. Thanks. :)

[anshikavashistha]

Thank you @berzi Could you please guide me as I am beginner for wagtail org and its functionality?

[berzi]

@anshikavashistha I myself haven't contributed yet. The Slack channel should be able to help you with any questions.

[anshikavashistha]

Okay great

[Lymah123]

Hi @zerolab , can I work on the issue?

[zerolab]

@Lymah123 and everyone else, please read https://github.com/wagtail/wagtail/blob/18a1101656a4c80ee33230f4c4e65df5cbfe5b71/.github/CONTRIBUTING.md

All newcomers, do join the #new-contributors channel in Slack for further help