Init reorg of docs for new notebooks

* Stop splitting notebooks into those that are rendered and those that are
not. It requires remembering to render the notebooks for the docs
separately. Now the docs notebooks are just symlinks to the notebooks in the
`notebooks/` dir.

* Update text/language around notebooks, and nest all notebooks under one
section in the docs

Author: trey-stafford

.gitignore

@@ -2,6 +2,10 @@
 docs/_build/
 docs/api/
 
+# Icepyx-related
+.order_restart
+notebooks/.order_restart
+
 # Temporary local data store
 downloaded-data/
 

docs/conf.py

@@ -80,3 +80,26 @@
 always_document_param_types = True
 
 nb_execution_mode = "off"
+
+
+def copy_notebook_images(app, _exception):
+    """Copy notebook static images into place post-build."""
+    import shutil
+    from pathlib import Path
+
+    source_dir = Path(app.srcdir) / ".." / "notebooks" / "img"
+    dest_dir = Path(app.outdir) / "notebooks" / "img"
+
+    if dest_dir.exists():
+        shutil.rmtree(dest_dir)
+
+    shutil.copytree(source_dir, dest_dir)
+
+
+def setup(app):
+    """Setup build-finished action to copy images into place.
+
+    Because the images are only referenced in jupyter notebooks, and not source
+    files parsed directly by sphinx, the images will not be copied on their own.
+    """
+    app.connect("build-finished", copy_notebook_images)

docs/contributing.md

@@ -61,10 +61,8 @@ jupyter lab
 ```
 
 Develop notebooks and confirm that they work as expected. Before committing
-changes, clear all outputs.
-
-See below for information about adding rendered versions of notebooks to
-ReadTheDocs.
+changes, ensure all cells are evaluated so that outputs are populated. These
+notebooks are included in the docs and will be displayed on ReadTheDocs.
 
 ## Documentation
 
@@ -82,6 +80,15 @@ live-reloading:
 inv docs.watch
 ```
 
+:::{note}
+
+Most of the content included in the rendered docs come from the `docs/` dir, but
+some is sourced from outside of `docs/`. For example, the Jupyter Notebooks are
+sourced from the project's `notebooks/` directory via symlinks to
+`docs/notebooks`.
+
+:::
+
 The docs are generated and hosted by
 [ReadTheDocs](https://iceflow.readthedocs.io/en/latest/).
 
@@ -90,15 +97,6 @@ Please review this carefully and ensure that any changes are accurately
 reflected. On a merge to main, changes to the documentation will be reflected on
 the main, public-facing documentation site.
 
-> [!NOTE] Most of the documentation is designed to be generated automatically.
-> E.g., changes to the API and markdown documents will be automatically
-> refelcted in the documentation. The one exception are the jupyter notebooks
-> (e.g., `iceflow-example.ipynb`), which are static and must be re-generated
-> manually. Use the `invoke docs.render-notebooks-for-docs` task to re-generate
-> these files, and then commit any changes to the repository. See the
-> `notebooks/generate_rendered_notebooks_for_docs.sh` for how to add new
-> rendered notebooks to the docs.
-
 ## Releasing
 
 To release a new version of the software, first update the CHANGELOG.md to
@@ -111,9 +109,11 @@ $ bump-my-version bump {major|minor|patch}
 
 This will update files containing the software version number.
 
-> [!WARNING]
->
-> Please do not attempt to update version numbers by hand!
+:::{warning}
+
+Please do not attempt to update version numbers by hand!
+
+:::
 
 Commit these changes and, once ready, merge them into `main` (through the use of
 a Pull Request on a feature branch). Tag the commit you want to release on

docs/getting-started.md

@@ -3,24 +3,8 @@
 ## Jupyter Notebooks
 
 [Jupyter notebooks](https://docs.jupyter.org/en/latest/) provide executable
-examples of how to use `iceflow`:
-
-- [iceflow-example.ipynb](./iceflow-example.ipynb) provides an example of how to
-  search for, download, and interact with `ILATM1B v1` data for a small area of
-  interest. This notebook also illustrates how to perform
-  [ITRF](https://itrf.ign.fr/) transformations to facilitate comparisons across
-  datasets. To learn more about ITRF transformations, see the
-  [corrections.ipynb](https://github.com/nsidc/NSIDC-Data-Tutorials/blob/main/notebooks/iceflow/corrections.ipynb)
-  notebook in the
-  [NSIDC-Data-Tutorials GitHub repository](https://github.com/nsidc/NSIDC-Data-Tutorials).
-
-- [iceflow-with-icepyx.ipynb](./iceflow-with-icepyx.ipynb) shows how to search
-  for, download, and interact with a large amount of data across many datasets
-  supported by `iceflow`. It also illustrates how to utilize
-  [icepyx](https://icepyx.readthedocs.io/en/latest/) to find and access ICESat-2
-  data. Finally, the notebook provides a simple time-series analysis for
-  elevation change over an area of interest across `iceflow` supported datasets
-  and ICESat-2.
+examples of how to use `iceflow`. See [Jupyter Notebooks](./notebooks/index.md)
+for more information.
 
 ## API overview