Documentation bugs

[adamjstewart]

This is a running list of bugs I've noticed in the documentation that need to be fixed.

• Sections don't have permalinks
• "Open in Colab" button is too wide: Unable to define width of image pytorch/pytorch_sphinx_theme#140, Allow images to define width pytorch/pytorch_sphinx_theme#142
• Fonts are missing, requiring hack to requirements.txt: Missing fonts pytorch/pytorch_sphinx_theme#143
• Dataset base class is incorrect: Incorrect base class detection sphinx-doc/sphinx#9607
• Models and trainers are missing args/returns documentation
• Tutorials don't run on Colab, need to clone from GitHub and install dependencies (or pip install once we release on PyPI)
• Notes on how to download SEN12MS and So2Sat aren't showing up (3d3b903, fd4998b)
• API docs show "Return type: None" for most functions, see if we can get rid of this (Docs: get rid of "Return type: None" for procedures with no return value #277)
• In-line code missing off-color background (The background of spaces within double backticks are not rendered correctly. pytorch/pytorch_sphinx_theme#130)
• the "well-tested" and "linters" links are broken on the users/contributing page (6d57250)
• NAIP has no docs because docstrings aren't inherited from parent classes
• BoundingBox docs aren't formatted correctly: https://torchgeo.readthedocs.io/en/latest/api/datasets.html#torchgeo.datasets.BoundingBox (Remove __module__ hacks #976)
• Nested lists have a lot of unnecessary whitespace: https://torchgeo.readthedocs.io/en/latest/api/datasets.html#torchgeo.datasets.SpaceNet1
• Models have extra undocumented parameters defined
• Trainer kwargs are showing up under parameters
• Versions popup menu appears on wrong side of the screen
• Versions popup menu does not have release versions, only latest and stable
• __getitem__ is showing up before __init__ because things are sorted alphabetically, we don't want this (Remove __module__ hacks #976)
• torchgeo.samplers.Units: possible enum values not displayed (Remove __module__ hacks #976)
• torchgeo.datasets.RasterDataset: class attributes not displayed (Remove __module__ hacks #976)

[calebrob6]

There is some incompatibility going on between the pytorch_sphinx_theme and nbsphinx. With nbsphinx enabled in conf.py:

• The sidebar navigation doesn't show expand/collapse buttons
• The sidebar navigation doesn't scroll with the page
• Sections don't have permalinks
• There are require.js errors on the page

[calebrob6]

^ the above issues I mentioned were resolved by adding nbsphinx_requirejs_path = "" in docs/conf.py

Some references:

• Incompatibility with nbsphinx pytorch/pytorch_sphinx_theme#148
• nbsphinx incompatibility with the pytorch_sphinx_theme  spatialaudio/nbsphinx#599

[adamjstewart]

We could consider switching to the trojanzoo_sphinx_theme which is forked off of pytorch_sphinx_theme but better maintained.

[adamjstewart]

If we do switch to trojanzoo_sphinx_theme, we'll be able to move docs/requirements.txt into setup.cfg

[adamjstewart]

__getitem__ is showing up before __init__ because things are sorted alphabetically, we don't want this

I believe this is caused by sphinx-doc/sphinx#9395. We're using the correct settings in our conf.py:

autodoc_member_order = "bysource"                                                        

However, Sphinx doesn't know where to locate the source code because we override __module__ in order for other things to work.

[robmarkcole]

There is an error in trainers.ipynb. The csv is created with upper case column names (e.g. train_RMSE). Cell fixed below:

train_steps = []
train_rmse = []

val_steps = []
val_rmse = []
with open(os.path.join(experiment_dir, "tutorial_logs", "version_0", "metrics.csv"), "r") as f:
    csv_reader = csv.DictReader(f, delimiter=',')
    for i, row in enumerate(csv_reader):
        try:
            # train_rmse.append(float(row["train_rmse"]))
            train_rmse.append(float(row["train_RMSE"]))
            train_steps.append(i)
        except ValueError: # Ignore rows where train RMSE is empty 
            pass

        try:
            # val_rmse.append(float(row["val_rmse"]))
            val_rmse.append(float(row["val_RMSE"]))
            val_steps.append(i)
        except ValueError: # Ignore rows where val RMSE is empty
            pass

[calebrob6]

Thanks for the catch / report @robmarkcole! This is one of the few things that isn't tested... Fixed in #434

[adamjstewart]

I think we can close this issue. Most remaining issues are documented in the pytorch-sphinx-theme repo. I want to change this in #2006