TODO: documentation improvements

[AdeelH]

Follow-up to #1501

Major

• Rewrite docs to emphasize the library aspect of RV (as opposed to the framework aspect). (Refactor usage documentation #1561)
• Rewrite README. (Update README #1590)
• Reorganize docs for better readability. (Refactor usage documentation #1561)
• Add more tutorial notebooks (Add example notebooks #1459, Add more notebooks + misc. doc fixes and improvements #1506, Add RV + Lightning notebook #1546)

Minor

• Disambiguate registry and rv_config from their respective module names. This causes problems for sphinx. (Add more notebooks + misc. doc fixes and improvements #1506)
• Link all mentions of classes/functions in notebooks to their respective API reference pages. (Add cross-references to API docs and other tutorials in tutorial notebooks #1586)
• Bug: currently links for some type hints are missing.
  • For example, Dataset, Optimizer, _LRScheduler, and Sampler in the docs for Learner are not linked to PyTorch docs whereas other classes like DataLoader and Tensor are. It is unclear why this happens. Could be a problem with the intersphinx mapping provided by PyTorch.
  • 'np.array' type hints are not linked when numpy is imported under if TYPE_CHECKING. This also applies to the ones in the point above.
• Ensure docstrings and type hints for the most frequently used classes/functions. (Improve docstrings for most commonly used classes and configs #1630)
• Consider switching theme to pydata_sphinx_theme.
• Add dosctrings for modules.
• Improve docstrings
  • Ensure Google-style docstring format everywhere.
  • [ ] Add Examples section to docstrings where appropriate (e.g. to Box methods).
  • Use rst formatting in docstrings where appropriate.
    • E.g. add .. note::s and .. seealso::s, add references to other objects.
  • Where feasible, replace *args, **kwargs in overridden methods with full list of arguments or link to the parent's documentation. (Misc. documentation improvements #1840)
• Consider using less automated API reference pages for modules. Example: https://github.com/scipy/scipy/blob/main/scipy/linalg/__init__.py.

[lewfish]

What do you think about making it so that you can hit a button next to the notebooks in the docs and it will open it in Google Colab? We will have to modify the notebooks to have a preamble section where we install RV and any other necessary setup.

[AdeelH]

I like that idea.

Here is an attempt:
0e31373

Result:
https://raster-vision--1506.org.readthedocs.build/en/1506/tutorials/reading_labels.html

[lewfish]

Looks good!

I noticed that when searching the docs for an argument to a Config class, the page I'm actually looking for is way down in the results. It seems to show links to source code before API docs. Maybe there's a way to specify a search path of sorts.

For example, when searching https://docs.rastervision.io/en/latest/search.html?q=max_windows, I want it to give me this link first https://docs.rastervision.io/en/latest/api_reference/_generated/rastervision.pytorch_learner.learner_config.GeoDataWindowConfig.html

[AdeelH]

Interestingly, the built-in sphinx search (which is used in local builds and PR builds) lists the correct result as the top result. But the actual deployed RTD build uses ElasticSearch, which returns different results. There does not seem to be a way to turn it off as far as I can tell, nor is it clear that we would want to.

There does seem to be a configuration option to down-rank certain pages though, which I have now set to down-rank source code pages -- that should move the correct result up a few places. We won't know if it works until the PR is merged though.

[AdeelH]

Some graphics that might be useful to include in the docs: