point documentation of this package to Plone docs

Author: erral

README.rst

@@ -12,13 +12,14 @@ and BLOBs to be configured in zope.conf.
 
 plone.supermodel handlers are registered.
 
-See the ``usage.rst`` doctest for more details.
+See the `image handling section of Plone documentation <https://6.docs.plone.org/classic-ui/images.html#all-image-scales-in-the-srcset>`_ to learn how to
+use the features provided by this package.
 
 
 Source Code
 ===========
 
- Note: This packages is licensed under a *BSD license*. 
+ Note: This packages is licensed under a *BSD license*.
  Please do not add dependencies on GPL code!
 
 Contributors please read the document `Process for Plone core's development <https://docs.plone.org/develop/coredev/docs/index.html>`_

plone/namedfile/usage.rst

@@ -403,100 +403,3 @@ We will test this with a dummy request, faking traversal::
     'text/plain'
     >>> request.response.getHeader('Content-Disposition')
     "attachment; filename*=UTF-8''test.txt"
-
-
-Image scales
-------------
-
-This package can handle the creation, storage, and retrieval of arbitrarily
-sized scaled versions of images stored in NamedImage or NamedBlobImage fields.
-
-Image scales are accessed via an @@images view that is available for any item
-providing ``plone.namedfile.interfaces.IImageScaleTraversable``.  There are
-several ways that you may reference scales from page templates.
-
-1. for full control you may do the tag generation explicitly::
-
-     <img tal:define="images context/@@images;
-                      thumbnail python: images.scale('image', width=64, height=64);"
-          tal:condition="thumbnail"
-          tal:attributes="src thumbnail/url;
-                          width thumbnail/width;
-                          height thumbnail/height" />
-
-   This would create an up to 64 by 64 pixel scaled down version of the image
-   stored in the "image" field.  It also allows for passing in additional
-   parameters supported by the ``scaleImage`` function from ``plone.scale``,
-   e.g. ``mode`` or ``quality``.
-
-   .. _`plone.scale`: https://pypi.org/project/plone.scale/
-
-2. for automatic tag generation with extra parameters you would use::
-
-     <img tal:define="images context/@@images"
-          tal:replace="structure python: images.tag('image',
-                       width=1200, height=800, mode='contain')" />
-
-3. It is possible to access scales via predefined named scale sizes, rather
-   than hardcoding the dimensions every time you access a scale.  The scale
-   sizes are found via calling a utility providing
-   ``plone.namedfile.interfaces.IAvailableSizes``, which should return a dict of
-   scale name => (width, height).  A scale called 'mini' could then be accessed
-   like this::
-
-     <img tal:define="images context/@@images"
-          tal:replace="structure python: images.tag('image', scale='mini')" />
-
-   This would use the predefined scale size "mini" to determine the desired
-   image dimensions, but still allow to pass in extra parameters.
-
-4. a convenience short-cut for option 3 can be used::
-
-     <img tal:replace="structure context/@@images/image/mini" />
-
-5. and lastly, the short-cut can also be used to render the unscaled image::
-
-     <img tal:replace="structure context/@@images/image" />
-
-
-Image scales and srcset
------------------------
-
-Nowadays modern browsers are able to render different images depending on their width
-if URLs and widths are correctly provided in an attribute called ``srcset``, and the rendered
-space is provided in the attribute ``sizes``.
-
-So one can do the following:
-
-.. code-block:: xml
-
-    <img tal:define="images context/@@images;"
-         tal:replace="structure python:images.srcset(sizes='90vw')" />
-
-
-This will render the ``img`` with the URLs of all scales configured in Plone, calculating the width
-of each of the scales and will add the ``sizes="90vw"`` attribute. 
-The ``sizes`` attribute instructs the browser to render
-the image that best fits, as it will take 90% of the current viewport width.
-
-This means that, for bigger screens, the browser will download a bigger scaled image, while for smaller screens, a smaller scaled image is enough.
-
-This also means that the developer does not need to worry about creating a specific scale.
-They only need to provide the correct media query to signal the required width.
-
-The ``scrset`` method of the ``@@images`` view also takes all other parameters that can be rendered in the ``img`` tag, such as ``title``, ``alt``, or ``loading``:
-
-.. code-block:: xml
-
-
-    <img tal:define="images context/@@images;"
-         tal:replace="structure python:images.srcset(sizes='90vw',
-                                                     alt='This is the alternative text',
-                                                     loading='lazy',
-                                                     css_class='rounded-img')" />
-
-
-.. note::
-
-    While using this approach may be useful for projects, using it in reusable add-ons is not recommended, because it may require overriding it to your needs in a project.
-    For such cases, use configurable picture variants instead.