Revamping our semantic segmentation and object detection models docs #5833

NicolasHug commented 2 years ago

Sister issue (for classification models): https://github.com/pytorch/vision/issues/5833

We're re-writing our models docs to make them clearer, simpler, and to properly document the upcoming multi-weight API. This issue is about adding docs for the detection and segmentation models.

Our latest new docs are currently here (this link is likely outdated by the time you look at it, but it doesn't matter; the skeleton is there). We created a separate section that will eventually be merged into the main one. We have documented a few models, but most of them are still missing. The list of models that still need docs is listed below. If you'd like to participate, please comment below with a message saying "I'm working on XYZ" where XYZ is a model, so that others don't pick the same as you do. To keep things simple, please submit one PR per model, but feel free to contribute more than one model.

How to write docs for a model

Note: below are detailed instructions. This makes it look more complicated than it actually is. Don't be scared!

A great place to start is to look a the changes in this PR that documents SqueezeNet. You'll need to do exactly the same for your model:

Create a new .rst file in https://github.com/pytorch/vision/tree/main/docs/source/models. The file should look like this, with a link to the original paper, and a list of the corresponding model builders. It should also mention the base model class and link to the .py file where it is defined.
Update the models list in https://github.com/pytorch/vision/blame/main/docs/source/models_new.rst to link to this new file (without the .rst suffix). Please keep the list alphabetically sorted
Update the docstring of each new model builder, similarly to this one.
- there is a 1:1 mapping between a model builder and a Weight enum. For example, the docstring of squeezenet1_0 makes direct references to SqueezeNet1_0_Weights.
- don't forget the autoclass directive in the docstring. This will auto-generate documentation for the Weight enums. You don't need to understand how this is done, but if you're curious, it's done here.
- don't forget to document the **kwargs parameter. Usually these are passed to the base class, but if they don't do anything, just document them as **kwargs: unsued.

To build the docs locally, please look at our contributing guide. You won't need to worry about the gallery example, so always use make html-noplot instead of make html to save time.

Please don't hesitate to ping us if you need any help / guidance or if you have any question!

Semantic segmentation: