Big doc revamp - simplify and improve the subpackage pages #4783

NicolasHug · 2021-10-28T15:55:25Z

This PR adds a minor update to the side TOC by changing the order and the title of the sections, instead of the non-informative module names (see screenshot) (EDIT: order was upated since screenshot).

This PR also adds a major update which consist in putting each function and class into their own page. This adds a few benefits:

it make the pages much shorter, and easier to navigate
it makes classes and functions more discoverable, as there is much more that fits into one screen
it makes the structure of each page easier to parse and understand, which will greatly help better organizing the docs in the future (see note below about models)
it will provide much better google analytics feedback

Note: the model page still needs a significant update, more PRs will come later.

Here are the rendered docs: https://945987-73328905-gh.circle-artifacts.com/0/docs/index.html vs the current docs: https://pytorch.org/vision/stable/index.html

facebook-github-bot · 2021-10-28T15:55:32Z

💊 CI failures summary and remediations

As of commit 3f48e2c (more details on the Dr. CI page):

2/2 failures introduced in this PR

2 failures not recognized by patterns:

Job	Step	Action
^{unittest_linux_cpu_py3.6}	^{Run tests}	🔁 rerun
^{unittest_macos_cpu_py3.6}	^{Run tests}	🔁 rerun

This comment was automatically generated by Dr. CI (expand for details).

Please report bugs/suggestions to the (internal) Dr. CI Users group.

Click here to manually regenerate this comment.

datumbox

I understand that more work is needed to iron out some of the issues but I think this is already a major improvement in terms of readability. I would be in favour of merging it and continue changes on a follow up PR.

oke-aditya

This is so awesome ❤️ @NicolasHug

I have few thoughts, hope you don't mind 😅

oke-aditya · 2021-10-30T13:21:55Z

docs/source/ops.rst


-torchvision.ops
-===============
+Operators


I wanted to suggest this from long time, current operators page look a bit bloated.
We should probably divide in sections.
E.g. operators on boxes, operators on masks, detection operators, etc.

Definitely, one positive thing about the changes in this PR is that it surfaces our current doc structure weaknesses and it makes them more obvious, which will allow us to fix them.

To keep things manageable though, I would leave this out for future improvements, otherwise there will be too many things to review at once

oke-aditya · 2021-10-30T13:21:58Z

docs/source/utils.rst

+    :template: function.rst

-.. autofunction:: draw_segmentation_masks
+    draw_bounding_boxes


And specific reason to change the order?
It's kinda nice to push make_grid down as we don't actively maintain it.

It's kinda nice to push make_grid down as we don't actively maintain it.

That'st the reason :)

oke-aditya · 2021-10-30T13:26:06Z

docs/source/index.rst

   :maxdepth: 2
   :caption: Package Reference

+   models


Somehow the brain of users is accustomed to see docs in the previous order.
It might be unpleasant to change to order. I love the previous order. And kind off in presentations related to torchvision, E.g. Francisco's at PyTorch day, he presents by the previous order,

Would love the old order :)

The old order is alphabetical, and might not reflect the order of what users may be looking for.

I think that users are more interested in models, transforms and ops than say i.o. operations, so I changed the order to reflect the importance of each section. Obviously it's not set in stone and I'm happy to hear other's thoughts, but I don't think we should worry too much about current readers' habits. It's still very obvious which section corresponds to what, so users will get used to this one fast :)

So let's arrange according to usage order. Simple LFU caching here 😄

Datasets like MNIST, ImageNet are universal, so probably everyone needs it.
Transforms to convert ToTensor etc Are almost in every code.
Models are not used all places.
Ops are then used a bit more scarce.
Utils, are least used I think,

So the order datasets, transforms, models, ops, utils :)

Thanks for the input @oke-aditya , I will update accordingly

oke-aditya · 2021-10-30T13:27:31Z

docs/source/models.rst


-torchvision.models
-##################
+Models and pre-trained weights


Probably write in Title Case. As that's how PyTorch docs on left are

I'm not sure they're using Title Case - see e.g. "Features for large-scale deployments" or "Autograd mechanics".

They're uing "Automatic Mixed Prececision" and "Distributed Data Parallel" and "Frequently Asked Questions" because these are commonly known and shortened AMP, DDP, FAQ, etc.

oke-aditya · 2021-10-30T13:29:56Z

docs/source/index.rst

+   ops
   io
-   models
   feature_extraction


I think We should club this with models, just after it.

We should club this with models

I agree, I think eventually we will move it into the "Models and pre-trained weights" section. It is torchvision.models.feature_extraction after all. But since the models section needs a much bigger revamp, I wanted to leave this out for now

fmassa

This looks great, thanks!

…4783) Reviewed By: datumbox Differential Revision: D32064695 fbshipit-source-id: 9a5dca1cf2ff702e7a631c473c408fe7ca496670

)

Put each transform into its own page

0e2dee0

pytorch-probot bot added the ciflow/default label Oct 28, 2021

facebook-github-bot added the cla signed label Oct 28, 2021

NicolasHug marked this pull request as draft October 28, 2021 15:58

NicolasHug added 11 commits October 29, 2021 17:23

Fix rendering issue

f9d1548

Do that for datasets too

e0b31d0

Fix warning?

37a847d

Done feature extraction

2137b8a

Done IO

6af38ff

done ops

9a32f15

more transforms

2c764ae

done utils

545c8c5

done models

550c4f1

Fix some bad docstring

3729219

Change order of sections in TOC

0c10ced

NicolasHug added enhancement module: documentation labels Oct 29, 2021

NicolasHug changed the title ~~NORMG Put each transform into its own page~~ Big doc revamp - simplify and improve the subpackage pages Oct 29, 2021

NicolasHug marked this pull request as ready for review October 29, 2021 23:07

datumbox approved these changes Oct 30, 2021

View reviewed changes

oke-aditya reviewed Oct 30, 2021

View reviewed changes

NicolasHug added 2 commits October 31, 2021 11:09

Merge branch 'main' of github.com:pytorch/vision into autosummary_maybe

0b4f7a8

Update order

bc210dc

fmassa approved these changes Nov 1, 2021

View reviewed changes

Merge branch 'main' into autosummary_maybe

3f48e2c

NicolasHug merged commit 5b61144 into main Nov 1, 2021

facebook-github-bot pushed a commit that referenced this pull request Nov 1, 2021

[fbsync] Big doc revamp - simplify and improve the subpackage pages (#…

2bbdca8

…4783) Reviewed By: datumbox Differential Revision: D32064695 fbshipit-source-id: 9a5dca1cf2ff702e7a631c473c408fe7ca496670

cyyever pushed a commit to cyyever/vision that referenced this pull request Nov 16, 2021

Big doc revamp - simplify and improve the subpackage pages (pytorch#4783

b753163

)

datumbox deleted the autosummary_maybe branch January 12, 2022 20:47

NicolasHug mentioned this pull request Jan 21, 2022

Doc pages are too long and it's hard to figure out which functions are supported #5242

Closed

Big doc revamp - simplify and improve the subpackage pages #4783

Big doc revamp - simplify and improve the subpackage pages #4783

Uh oh!

Conversation

NicolasHug commented Oct 28, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

facebook-github-bot commented Oct 28, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

💊 CI failures summary and remediations

2 failures not recognized by patterns:

Uh oh!

datumbox left a comment

Choose a reason for hiding this comment

Uh oh!

oke-aditya left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oke-aditya Oct 31, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

NicolasHug Oct 31, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fmassa left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

NicolasHug commented Oct 28, 2021 •

edited

Loading

facebook-github-bot commented Oct 28, 2021 •

edited

Loading

oke-aditya Oct 31, 2021 •

edited

Loading

NicolasHug Oct 31, 2021 •

edited

Loading