add notebooks to the docs

Author: andersy005

docs/background/index.rst

@@ -0,0 +1,55 @@
+Background
+==========
+
+These articles explain the concepts, theory, and design decisions behind scikit-downscale and statistical downscaling methods.
+
+.. note::
+   Background articles are explanatory and conceptual. They provide context and deeper understanding but are not task-oriented.
+
+Coming Soon
+-----------
+
+We are actively developing background articles. Future topics will include:
+
+Statistical Downscaling Concepts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* What is statistical downscaling?
+* Bias correction vs. spatial disaggregation
+* When to use statistical vs. dynamical downscaling
+* Understanding quantile mapping
+* Stationarity assumptions in downscaling
+
+Method Comparisons
+~~~~~~~~~~~~~~~~~~
+
+* Comparing downscaling methods: strengths and weaknesses
+* Performance metrics for evaluating downscaling
+* Handling extremes in downscaling
+* Temporal and spatial consistency
+
+Design and Architecture
+~~~~~~~~~~~~~~~~~~~~~~~
+
+* Why scikit-learn's API?
+* Pointwise vs. spatial downscaling approaches
+* Integration with Xarray and Dask
+* Extensibility and custom methods
+
+Related Documentation
+---------------------
+
+While we develop these articles, you might find these resources helpful:
+
+* :doc:`../tutorials/index` - Hands-on learning with examples
+* :doc:`../roadmap` - Project development roadmap
+* `Scientific References <https://scikit-downscale.readthedocs.io>`_ - Key papers and methods
+
+External Resources
+------------------
+
+For broader context on statistical downscaling:
+
+* `Gutmann et al. (2014) <https://journals.ametsoc.org/view/journals/clim/27/23/jcli-d-13-00503.1.xml>`_ - Intercomparison of statistical downscaling methods
+* `Maraun et al. (2010) <https://journals.ametsoc.org/view/journals/clim/23/21/2010jcli3557.1.xml>`_ - Precipitation downscaling under climate change
+* `IPCC AR6 WG1 Chapter 10 <https://www.ipcc.ch/report/ar6/wg1/>`_ - Linking global to regional climate change

docs/conf.py

@@ -31,6 +31,11 @@
 myst_enable_extensions = ['amsmath', 'colon_fence', 'deflist', 'html_image']
 myst_url_schemes = ['http', 'https', 'mailto']
 
+# Jupyter notebook config
+nb_execution_mode = 'auto'  # Don't execute notebooks during build
+nb_execution_allow_errors = False
+nb_execution_timeout = 300
+
 # sphinx-copybutton configurations
 copybutton_prompt_text = r'>>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: '
 copybutton_prompt_is_regexp = True

docs/how-to/index.rst

@@ -0,0 +1,30 @@
+How-to Guides
+=============
+
+These guides provide step-by-step instructions for accomplishing specific tasks with scikit-downscale.
+
+.. note::
+   How-to guides are task-oriented and focus on solving specific problems. They assume you have basic familiarity with scikit-downscale.
+
+Coming Soon
+-----------
+
+We are actively developing how-to guides. Future topics will include:
+
+* Working with spatial data using PointWiseDownscaler
+* Handling missing data in climate datasets
+* Creating custom downscaling methods
+* Parallel processing with Dask
+* Cross-validation strategies for downscaling
+* Ensemble downscaling approaches
+* Downscaling multiple variables simultaneously
+
+Have a specific task in mind? Let us know by opening an issue on our `GitHub repository <https://github.com/jhamman/scikit-downscale/issues>`_.
+
+Related Documentation
+---------------------
+
+While we develop these guides, you might find these resources helpful:
+
+* :doc:`../tutorials/index` - Learn downscaling fundamentals
+* :doc:`../api` - Detailed API reference

docs/index.rst

@@ -1,36 +1,83 @@
-.. scikit-downscale documentation master file, created by
-   sphinx-quickstart on Wed Oct  9 13:59:33 2019.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Scikit-downscale: toolkit for statistical downscaling
 =====================================================
 
 Scikit-downscale is a toolkit for statistical downscaling using Scikit-Learn_.
 It is meant to support the development of new and existing downscaling
 methods in a common framework. It implements Scikit-learn's `fit`/`predict` API
-facilitating the development of a wide range of statitical downscaling models.
+facilitating the development of a wide range of statistical downscaling models.
 Utilities and a high-level API built on Xarray_ and Dask_ support both
 point-wise and global downscaling applications.
 
 .. _Xarray: http://xarray.pydata.org
 .. _Scikit-Learn: https://scikit-learn.org
 .. _Dask: https://dask.org
 
+Quick Start
+-----------
+
+Install scikit-downscale:
+
+.. code-block:: bash
+
+   pip install scikit-downscale
+
+Then try your first downscaling example:
+
+.. code-block:: python
+
+   from skdownscale.pointwise_models import QuantileMapper
+
+   # Initialize the model
+   qm = QuantileMapper()
+
+   # Fit on training data
+   qm.fit(model_data, observations)
+
+   # Generate downscaled predictions
+   downscaled = qm.predict(model_data)
+
+Ready to learn more? Check out our :doc:`tutorials/getting-started`!
+
+Documentation Structure
+-----------------------
+
+This documentation is organized following the `Diátaxis framework <https://diataxis.fr/>`_:
+
+📚 **Tutorials** - *Learning-oriented*
+   Step-by-step lessons to learn scikit-downscale. Start here if you're new!
+
+🔧 **How-to Guides** - *Problem-oriented*
+   Practical guides for accomplishing specific tasks.
+
+📖 **Background** - *Understanding-oriented*
+   Explanations of concepts, theory, and design decisions.
+
+📋 **Reference** - *Information-oriented*
+   Complete API documentation and technical specifications.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Documentation
+
+   tutorials/index
+   how-to/index
+   background/index
+   api
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Project Info
+
+   roadmap
+
 Under Active Development
 ~~~~~~~~~~~~~~~~~~~~~~~~
+
 Scikit-downscale is under active development. We are looking for additional
 contributors to help fill out the list of downscaling methods supported here.
 We are also looking to find collaborators interested in using deep learning
 to build global downscaling tools. Get in touch with us on our
-`GitHub page <https://github.com/jhamman/scikit-downscale>`_.
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
-
-   roadmap
-   api
+`GitHub page <https://github.com/pangeo-data/scikit-downscale>`_.
 
 Indices and tables
 ==================