Various doc enhancements #7326

NicolasHug · 2023-02-24T12:24:24Z

No description provided.

NicolasHug · 2023-02-24T12:25:33Z

torchvision/transforms/transforms.py

@@ -105,7 +105,9 @@ def __repr__(self) -> str:


 class ToTensor:
-    """Convert a ``PIL Image`` or ``numpy.ndarray`` to tensor. This transform does not support torchscript.
+    """Convert a ``PIL Image`` or ``numpy.ndarray`` to tensor and scale the values accordingly.


Note that in a bunch of these I had to remove the full dots on those first sentences, because otherwise sphinx would stop after the first . when rendering the "preview" which would truncate relevant info.

We always mention "PIL Image" without ticks and numpy ndarray as "ndarray". It would worth to keep things similar everywhere ?

maybe, but honestly I'd rather do that kind of changes later. The use of ticks doesn't come from this PR

NicolasHug · 2023-02-24T12:25:46Z

torchvision/transforms/v2/_meta.py

@@ -9,7 +9,7 @@


 class ConvertBoundingBoxFormat(Transform):
-    """[BETA] Convert bounding box coordinates to the given ``format``, e.g. from "CXCYWH" to "XYXY".
+    """[BETA] Convert bounding box coordinates to the given ``format``, eg from "CXCYWH" to "XYXY".


e.g. here, had to remove full dot

NicolasHug · 2023-02-24T12:26:15Z

torchvision/transforms/v2/_misc.py


    .. betastatus:: ToDtype transform

    Args:
-        dtype (dtype or dict of Datapoint -> dtype): The dtype to convert to. A dict can be passed to specify
+        dtype (``torch.dtype`` or dict of ``Datapoint`` -> ``torch.dtype``): The dtype to convert to.


wrapping in double quotes seems to fix the sad formatting you noticed @pmeier . We should fix those on the rest of the docs

pmeier

As an overarching comment: Should we invert the logic and warn users on the transforms that do scale the values? This is outlier behavior and AFAIK only exhibited by ToTensor, which is why we deprecated it. Granted, ToImagePIL also does, but this out of necessity, since PIL does not support RGB float images.

pmeier · 2023-02-24T12:54:40Z

docs/source/conf.py

@@ -34,6 +34,7 @@
 sys.path.append(os.path.abspath("."))

 torchvision.disable_beta_transforms_warning()
+import torchvision.datapoints  # Don't remove, otherwise the docs for datapoints aren't linked properly


Could you explain what is happening?

honestly I have no idea.

pmeier · 2023-02-24T12:55:27Z

docs/source/datapoints.rst

@@ -2,6 +2,12 @@ Datapoints
 ==========

 .. currentmodule:: torchvision.datapoints
+
+Datapoints are tensor subclasses which the v2 transforms use under the hood to


Suggested change

Datapoints are tensor subclasses which the v2 transforms use under the hood to

Datapoints are tensor subclasses which :mod:`~torchvision.transforms.v2` uses under the hood to

I'm not sure this is what we want, this just renders as v2 and isn't linked to anything

docs/source/transforms.rst

pmeier · 2023-02-24T12:56:55Z

torchvision/transforms/v2/_container.py

-            raise ValueError(
-                f"Length of p doesn't match the number of transforms: " f"{len(p)} != {len(transforms)}"
-            )
+            raise ValueError(f"Length of p doesn't match the number of transforms: " f"{len(p)} != {len(transforms)}")


This is coming from a lint failure on main.

pmeier · 2023-02-24T12:58:47Z

torchvision/transforms/v2/_misc.py


    .. betastatus:: ToDtype transform

    Args:
-        dtype (dtype or dict of Datapoint -> dtype): The dtype to convert to. A dict can be passed to specify
+        dtype (``torch.dtype`` or dict of ``Datapoint`` -> ``torch.dtype``): The dtype to convert to.
+            A dict can be passed to specify


This line looks oddly short. Shouldn't it be merged with the one below?

OK but it doesn't matter at all for the rendering, so let's please not worry too much about such details at this time

pmeier · 2023-02-24T12:59:22Z

torchvision/transforms/v2/_type_conversion.py

@@ -27,7 +27,8 @@ def _transform(self, inpt: PIL.Image.Image, params: Dict[str, Any]) -> torch.Ten


 class ToImageTensor(Transform):
-    """[BETA] Convert a tensor or an ndarray or PIL Image to :class:`~torchvision.datapoints.Image`.
+    """[BETA] Convert a tensor, ndarray, or PIL Image to :class:`~torchvision.datapoints.Image`
+    ; this does not scale values.


Consistency with all other docstrings.

Suggested change

; this does not scale values.

- this does not scale values.

I went for ; because I suspect sphinx to treat the - as a list entry as it's the first character of the line

torchvision/transforms/transforms.py

torchvision/transforms/v2/_container.py

Co-authored-by: Philip Meier <[email protected]>

Co-authored-by: vfdev <[email protected]>

NicolasHug · 2023-02-24T13:35:52Z

comments were addressed @pmeier @vfdev-5

Should we invert the logic and warn users on the transforms that do scale the values? This is outlier behavior and AFAIK only exhibited by ToTensor, which is why we deprecated it. Granted, ToImagePIL also does, but this out of necessity, since PIL does not support RGB float images.

Sorry I don't understand. We don't warn about anything right now, I just documented the behaviour of all transforms w.r.t. scaling vs non-scaling. I think we should document that for all of them, not just those that scale.

torchvision/transforms/v2/_deprecated.py

torchvision/transforms/v2/_type_conversion.py

vfdev-5

LGTM, thanks @NicolasHug !

github-actions · 2023-02-24T13:46:37Z

Hey @NicolasHug!

You merged this PR, but no labels were added. The list of valid labels is available at https://github.com/pytorch/vision/blob/main/.github/process_commit.py

Co-authored-by: Philip Meier <[email protected]> Co-authored-by: vfdev <[email protected]>

Summary: Reviewed By: vmoens Differential Revision: D44416641 fbshipit-source-id: 71db4e469d74407ef0319056a3b76bf4b502cb44 Co-authored-by: Philip Meier <[email protected]> Co-authored-by: vfdev <[email protected]>

Various doc enhancements

14c73ff

NicolasHug requested review from vfdev-5 and pmeier February 24, 2023 12:24

facebook-github-bot added the cla signed label Feb 24, 2023

NicolasHug commented Feb 24, 2023

View reviewed changes

Some more

470ac9c

pmeier reviewed Feb 24, 2023

View reviewed changes

vfdev-5 reviewed Feb 24, 2023

View reviewed changes

torchvision/transforms/transforms.py Outdated Show resolved Hide resolved

vfdev-5 reviewed Feb 24, 2023

View reviewed changes

torchvision/transforms/transforms.py Outdated Show resolved Hide resolved

vfdev-5 reviewed Feb 24, 2023

View reviewed changes

torchvision/transforms/v2/_container.py Outdated Show resolved Hide resolved

NicolasHug and others added 4 commits February 24, 2023 13:32

Update docs/source/transforms.rst

6d6063a

Co-authored-by: Philip Meier <[email protected]>

Update torchvision/transforms/transforms.py

0a2407f

Co-authored-by: vfdev <[email protected]>

Apply suggestions from code review

b0999a9

Co-authored-by: vfdev <[email protected]>

comment

4f481dd

vfdev-5 reviewed Feb 24, 2023

View reviewed changes

torchvision/transforms/v2/_deprecated.py Outdated Show resolved Hide resolved

Update torchvision/transforms/v2/_deprecated.py

3602052

vfdev-5 reviewed Feb 24, 2023

View reviewed changes

torchvision/transforms/v2/_type_conversion.py Outdated Show resolved Hide resolved

Update torchvision/transforms/v2/_type_conversion.py

1529d95

vfdev-5 approved these changes Feb 24, 2023

View reviewed changes

NicolasHug merged commit 877ffd9 into pytorch:main Feb 24, 2023

NicolasHug added a commit to NicolasHug/vision that referenced this pull request Feb 24, 2023

Various doc enhancements (pytorch#7326)

f62a045

Co-authored-by: Philip Meier <[email protected]> Co-authored-by: vfdev <[email protected]>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Various doc enhancements #7326

Various doc enhancements #7326

NicolasHug commented Feb 24, 2023

NicolasHug Feb 24, 2023

vfdev-5 Feb 24, 2023

NicolasHug Feb 24, 2023

NicolasHug Feb 24, 2023

NicolasHug Feb 24, 2023

pmeier left a comment

pmeier Feb 24, 2023

NicolasHug Feb 24, 2023

pmeier Feb 24, 2023

NicolasHug Feb 24, 2023

pmeier Feb 24, 2023

pmeier Feb 24, 2023

NicolasHug Feb 24, 2023

pmeier Feb 24, 2023

NicolasHug Feb 24, 2023

NicolasHug commented Feb 24, 2023

vfdev-5 left a comment

github-actions bot commented Feb 24, 2023

	Datapoints are tensor subclasses which the v2 transforms use under the hood to
	Datapoints are tensor subclasses which :mod:`~torchvision.transforms.v2` uses under the hood to

Various doc enhancements #7326

Various doc enhancements #7326

Conversation

NicolasHug commented Feb 24, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pmeier left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

NicolasHug commented Feb 24, 2023

vfdev-5 left a comment

Choose a reason for hiding this comment

github-actions bot commented Feb 24, 2023