[FEEDBACK] Documentation revamp: New layout, New models docs

[datumbox]

📚 Feedback Request

This issue is dedicated for collecting community feedback on the Documentation revamping efforts. Here are some highlighted changes:

• New documentation layout: Each function / class is now documented in a separate page, clearing up some space in the per-module pages, and easing the discovery of the proposed APIs. Compare e.g. our previous docs vs the new ones.
• New models docs: With the upcoming multi-weight API, we took this opportunity to completely re-write our models documentation. We now have a main model page with various summary tables of available weights, and each model has a dedicated page. Each model builder is also documented in their own page, with more details about the available weights. For comparison, our previous models docs are here.
  We would love to get your thoughts, comments and input on how to improve our documentation.

[yassineAlouini]

I am new to the PyTorch OSS ecosystem and wanted to get started so any documentation help might be a good place to start for me.

I can give this a look. However it seems that the 0.12 version can't be displayed online. Or maybe one needs to run it locally?

[NicolasHug]

We haven't pushed them yet, but they're currently at https://pytorch.org/vision/main/transforms.html
@datumbox I took the liberty to fix the link in your message

[yassineAlouini]

@NicolasHug Thanks for the quick response, it makes sense that these are built from a commit and not from a released version. 👌

What is the best feedback format that will help you in your investigation?

[yassineAlouini]

The new layout is better in the sense that each function has more space to grow now that it is in its own page so longer examples can be added.

One enhancement that I can see coming is slightly more details in the table view: for instance, adding the arguments types. This might be tricky to do maybe? I guess for now the new layout uses the short description part from docstrings to build the table.

In anyway, looks good so far. 👍

[datumbox]

The majority of work around the documentation is now complete. We'll leave the issue open to get the input of the community for further improvements.

[agunapal]

There is a lot of good documentation on model weights and model usage details. One suggestion would be to provide a link to https://pytorch.org/vision/main/models.html#table-of-all-available-classification-weights here https://pytorch.org/vision/main/models.html#initializing-pre-trained-models . I tried figuring out weight names for various models from the code . I found the link to the weights later when I scrolled down.

[datumbox]

@mrinath123 Thanks for the feedback.

I would recommend starting a new issue to discuss this in more detail, so that we can keep this one focused on the documentation. But note that your feedback is very valid and the Detection submodule needs some love. I will hold off from adding details here, let's chat about it on the new issue. Feel free to cc me and I'll post some potential workarounds for now. Again thanks for raising this.

[ain-soph]

The new documentation content is pretty clean and well-structured. I especially like the updated model page.

I just have a minor complaint about the category/page/section names. Previously in 0.11, it's torchvision.models, torchvision.transforms, etc. They are classified w.r.t. the module names, which makes me very clear where I am.
However, the current docs makes me feel like a textbook/tutorial rather than an API doc. I usually get lost and raise the question :"Where am I? Which module am I currently at?"

Old docs index before 0.12

New doc index after 0.12

[datumbox]

@ain-soph Thanks for the feedback, it's definitely something we can look into on the near future.

[ain-soph]

And another thought to improve docs in terms of sphinx theme.

In my case, I find it extremely helpful to index methods of classes into the right sidebar.
https://ain-soph.github.io/trojanzoo/trojanzoo/models.html

But it seems currently torchvision doesn't have such demand to index class methods. Any opinion on this?

[abhi-glitchhg]

@ain-soph I really liked your sphinx theme, especially dynamically changing right sidebar.

[datumbox]

Another proposal that came originally from @NicolasHug was to keep permanently on the docs a reference of which weights mapped to the pretrained=True. This can be useful for when one tries to find which weights were used in old code, long after the pretrained parameter is deprecated.

One potential solution was tried at #5993 but there were few limitations that we could't address. So either we need to introduce another annotation OR we could add manually a note on the doc that the specific set of weights was the one that linked to pretrained=True.

[davidgilbertson]

Some things appear to be missing from the docs. E.g. torchvision.models.detection.backbone_utils.

I second @ain-soph 's comment that it's nice when docs mimic the structure of the actual package, presumably this also makes it easier to generate the docs and keep them up to date since it's a more direct mapping.