pytorch / pytorch/vision

automatic xref links in the galleries are wrong

Open
#7,307 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

module: documentation
Dominant language
Python
Stars
17.9k
Forks
7.3k
Avg merge
1d 15h
Merged PRs (30d)
13

Description

sphinx-gallery seems to automatically create xref links for stuff that we use in the code blocks. However, these links seem to be wrong.

For example, all the transforms in https://pytorch.org/vision/0.14/auto_examples/plot_transforms.html#sphx-glr-auto-examples-plot-transforms-py link to https://pytorch.org/docs/stable/generated/torch.nn.Module.html#torch.nn.Module.

Not available in the stable documentation yet, but datasets.CocoDetection from #7302 links to https://pytorch.org/docs/stable/data.html#torch.utils.data.Dataset

At the same time, there seem to be no xref links for "pure" torchvision stuff. For example, no xref is generated for read_image from torchvision.io in https://pytorch.org/vision/0.14/auto_examples/plot_scripted_tensor_transforms.html#sphx-glr-auto-examples-plot-scripted-tensor-transforms-py although there is documentation for it: https://pytorch.org/vision/0.14/generated/torchvision.io.read_image.html?highlight=read_image#torchvision.io.read_image

Curiously, this xref seems to work the other way around. For example, the documentation for read_image correctly identifies that it is used in multiple examples.

Given that the links are either non-existent or point to the PyTorch base class, maybe sphinx-gallery just has a problem with the package that the galleries belong to?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the automatic xref links in the Sphinx-Gallery examples cited in issue #7307, comparing torchvision symbols such as read_image and datasets.CocoDetection with the generated links. Trace how the gallery documentation identifies symbols from code blocks; done means torchvision references resolve to their torchvision documentation pages and incorrect base-class links are corrected.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.