Open AdeelH opened 2 years ago
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.
I like that idea.
Here is an attempt: https://github.com/azavea/raster-vision/pull/1506/commits/0e31373f5b5d9b7b21325466d557c42eb2c61261
Result: https://raster-vision--1506.org.readthedocs.build/en/1506/tutorials/reading_labels.html
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
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.
Some graphics that might be useful to include in the docs:
Follow-up to #1501
Major
Minor
registry
andrv_config
from their respective module names. This causes problems forsphinx
. (#1506)Dataset
,Optimizer
,_LRScheduler
, andSampler
in the docs forLearner
are not linked to PyTorch docs whereas other classes likeDataLoader
andTensor
are. It is unclear why this happens. Could be a problem with theintersphinx
mapping provided by PyTorch.'np.array'
type hints are not linked whennumpy
is imported underif TYPE_CHECKING
. This also applies to the ones in the point above.pydata_sphinx_theme
.~Examples
section to docstrings where appropriate (e.g. toBox
methods).~.. note::
s and.. seealso::
s, add references to other objects.*args, **kwargs
in overridden methods with full list of arguments or link to the parent's documentation. (#1840)