Add tutorials to documentation

docs/api/datasets.rst

@@ -3,7 +3,9 @@ torchgeo.datasets
 
 .. module:: torchgeo.datasets
 
-In :mod:`torchgeo`, we define two types of datasets: :ref:`Geospatial Datasets` and :ref:`Non-geospatial Datasets`. These abstract base classes are documented in more detail in :ref:`Dataset Base Classes`.
+In :mod:`torchgeo`, we define two types of datasets: :ref:`Geospatial Datasets` and :ref:`Non-geospatial Datasets`. These abstract base classes are documented in more detail in :ref:`Base Classes`.
+
+.. _Geospatial Datasets:
 
 Geospatial Datasets
 -------------------
@@ -60,6 +62,8 @@ Sentinel
 .. autoclass:: Sentinel
 .. autoclass:: Sentinel2
 
+.. _Non-geospatial Datasets:
+
 Non-geospatial Datasets
 -----------------------
 
@@ -107,8 +111,10 @@ NWPU VHR-10
 
 .. autoclass:: VHR10
 
-Dataset Base Classes
---------------------
+.. _Base Classes:
+
+Base Classes
+------------
 
 If you want to write your own custom dataset, you can extend one of these abstract base classes.
 

docs/api/samplers.rst

@@ -52,8 +52,8 @@ Random Batch Geo Sampler
 
 .. autoclass:: RandomBatchGeoSampler
 
-Sampler Base Classes
---------------------
+Base Classes
+------------
 
 If you want to write your own custom sampler, you can extend one of these abstract base classes.
 

docs/conf.py

@@ -34,11 +34,11 @@ release = torchgeo.__version__
 # 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,16 @@ intersphinx_mapping = {
     "rtree": ("https://rtree.readthedocs.io/en/latest/", None),
     "torch": ("https://pytorch.org/docs/stable", None),
 }
+
+# nbsphinx
+# 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 }}
+"""

docs/index.rst

@@ -13,17 +13,32 @@ architectures, and common image transformations for geospatial data.
    :maxdepth: 2
    :caption: Package Reference
 
-   datasets
-   models
-   samplers
-   trainers
-   transforms
+   api/datasets
+   api/models
+   api/samplers
+   api/trainers
+   api/transforms
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Tutorials
+
+   tutorials/GeoDataset
+   tutorials/Benin Smallholder Cashew Plantations Dataset
+   tutorials/SEN12MS Dataset
+   tutorials/Canadian Building Footprints Dataset
+   tutorials/Landcover.ai Dataset
+   tutorials/So2Sat Dataset
+   tutorials/Chesapeake Dataset
+   tutorials/NAIP Dataset
+   tutorials/CV4A Kenya Crop Type Dataset
+   tutorials/NASA Cyclone Dataset
 
 .. toctree::
    :maxdepth: 2
    :caption: User Documentation
 
-   glossary
+   user/glossary
 
 .. toctree::
    :maxdepth: 1

environment.yml

@@ -19,6 +19,7 @@ dependencies:
     - isort[colors]>=5.8
     - jupyterlab
     - mypy>=0.900
+    - npsphinx>=0.8.5
     - omegaconf>=2.1
     - opencv-python
     - pillow>=2.9

requirements.txt

@@ -12,6 +12,8 @@ jupyterlab
 matplotlib
 # mypy 0.900+ required for pyproject.toml support
 mypy>=0.900
+# nbsphinx 0.8.5 fixes bug with nbformat attributes
+nbsphinx>=0.8.5
 numpy
 # omegaconf 2.1+ required for to_object method
 omegaconf>=2.1

setup.cfg

@@ -52,6 +52,7 @@ datasets =
 # Optional developer requirements
 docs =
     jupyterlab
+    npbsphinx>=0.8.5
     sphinx>=3
     pydocstyle[toml]>=6.1
     pytorch-sphinx-theme

spack.yaml

@@ -11,6 +11,7 @@ spack:
   - "py-jupyterlab"
   - "py-matplotlib"
   - "py-mypy@0.900:"
+  - "py-nbsphinx@0.8.5:"
   - "py-numpy"
   - "py-omegaconf@2.1:"
   - "py-pycocotools"