Repository: microsoft/torchgeo

Issue:
Jupyter Notebook tutorials
We need to figure out how to render Jupyter Notebooks in our documentation so that we can provide easy-to-use tutorials for new users. This should work similarly to https://pytorch.org/tutorials/.

Ideally I would like to be able to test these tutorials so that they stay up-to-date.


Discussion:
Here is another example of how to do this: https://github.com/PyTorchLightning/lightning-tutorials
Started looking into this. You can directly render a notebook using `nbsphinx`. `pandoc` is required if you have any markdown in your notebook. This is what Lightning does for their tutorials.

However, PyTorch does something completely different. They instead store the file as a `.py` file and encode the rst in comments. I'm guessing this makes it easier to test? Not sure how this gets automatically converted to a notebook when you open in Google Colab/MS Learn.
Another option is nbsphinx: https://nbsphinx.readthedocs.io/en/0.8.7/ That's what's used in dask-examples: https://github.com/dask/dask-examples, which are rendered at https://examples.dask.org/.
On the thread of running and testing notebooks to make sure they remain up-to-date, `nbmake` seems like a good way to integrate things with `pytest`: https://semaphoreci.com/blog/test-jupyter-notebooks-with-pytest-and-nbmake

However, that requires a specific conda environment to be active, which I don't want. Also, we'll need all dependencies installed and have data available. Some of these training loops could be very time-intensive to run.

Resolving patch:
diff --git a/docs/conf.py b/docs/conf.py
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -34,11 +34,11 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
-    "sphinx.ext.autosectionlabel",
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
     "sphinx.ext.todo",
     "sphinx.ext.viewcode",
+    "nbsphinx",
 ]
 
 # List of patterns, relative to source directory, that match files and
@@ -97,3 +97,17 @@
     "rtree": ("https://rtree.readthedocs.io/en/latest/", None),
     "torch": ("https://pytorch.org/docs/stable", None),
 }
+
+# nbsphinx
+nbsphinx_execute = "never"
+# TODO: branch/tag should change depending on which version of docs you look at
+# TODO: :width: may be broken
+nbsphinx_prolog = """
+{% set colab = "https://colab.research.google.com" %}
+{% set repo = "microsoft/torchgeo" %}
+{% set branch = "main" %}
+
+.. image:: {{ colab }}/assets/colab-badge.svg
+    :alt: Open in Colab
+    :target: {{ colab }}/github/{{ repo }}/blob/{{ branch }}/docs/{{ env.docname }}
+"""


Test patch:
diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml
--- a/.github/workflows/tests.yaml
+++ b/.github/workflows/tests.yaml
@@ -30,7 +30,7 @@ jobs:
     - name: Install dependencies
       run: |
         pip install cython numpy  # needed for pycocotools
-        pip install --pre -r requirements.txt
+        pip install -r requirements.txt
     - name: Run mypy checks
       run: mypy .
   pytest:
@@ -72,7 +72,7 @@ jobs:
     - name: Install pip dependencies
       run: |
         pip install cython numpy  # needed for pycocotools
-        pip install --pre -r requirements.txt
+        pip install -r requirements.txt
         pip list
     - name: Run pytest checks
-      run: pytest --cov=. --cov-report=term-missing
+      run: pytest --cov=torchgeo --cov-report=term-missing
diff --git a/tests/test_setup.py b/tests/test_setup.py
--- a/tests/test_setup.py
+++ b/tests/test_setup.py
@@ -2,6 +2,10 @@
 import sys
 from pathlib import Path
 
+import pytest
+
+pytestmark = pytest.mark.slow
+
 
 def test_install(tmp_path: Path) -> None:
     subprocess.run(
diff --git a/tests/test_train.py b/tests/test_train.py
--- a/tests/test_train.py
+++ b/tests/test_train.py
@@ -6,6 +6,8 @@
 
 import pytest
 
+pytestmark = pytest.mark.slow
+
 
 def test_required_args() -> None:
     args = [sys.executable, "train.py"]