-
Notifications
You must be signed in to change notification settings - Fork 384
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
TODO: documentation improvements #1505
Comments
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: Result: |
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. |
Follow-up to #1501
Major
Minor
registry
andrv_config
from their respective module names. This causes problems forsphinx
. (Add more notebooks + misc. doc fixes and improvements #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.Consider switching theme topydata_sphinx_theme
.[ ] AddExamples
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. (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.The text was updated successfully, but these errors were encountered: