Update docs, add jupyter example

docs/getting_started.md

@@ -3,8 +3,8 @@
 The roughness python model requires 3 components to run:
 
 - The package itself (see installation instructions)
-- A raytrace shadowing lookup table (see [make_los_table](make_los_table.md))
-- A temperature lookup table (see [make_temp_table](make_temp_table.md))
+- A raytrace shadowing lookup table (see [make_los_table](reference/make_los_table.md))
+- A temperature lookup table (see [Temperature Tables](../temperature_tables/))
 
 Basic versions of the generaic shadowing table and lunar temperature lookup table are provided on Zenodo (coming soon), but custom versions of each can be generated using the tools in the roughness package.
 
@@ -53,4 +53,4 @@ emission = rtm.emission(geometry, wavelengths, rms, tparams)  # returns xarray
 emission.plot() # Plot emitted radiance vs. wavelength
 ```
 
-For more examples, see the [examples](examples.md) page.
+See [Rough Emission](../rough_emission/) for a more detailed example.

docs/requirements.txt

@@ -1,6 +1,7 @@
-mkdocs==1.4.3
-mkdocs-material==6.2.8
+mkdocs==1.5.2
+mkdocs-material==9.1.21
 mkdocs-gen-files==0.5.0
 mkdocs-literate-nav==0.6.0
 mkdocstrings==0.22.0
-mkdocstrings-python==1.1.2
+mkdocstrings-python==1.3.0
+mkdocs-jupyter==0.24.2

mkdocs.yml

@@ -36,6 +36,10 @@ plugins:
           paths: [roughness]
   - literate-nav:
       nav_file: SUMMARY.md
+  - mkdocs-jupyter:
+      include_source: true
+      execute: true
+      allow_errors: false
 
 # Footer
 extra:
@@ -49,10 +53,14 @@ nav:
   - Home: index.md
   - 'User Guide':
     - 'Getting Started': 'getting_started.md'
-    - 'Examples': examples.md
+    - 'Shadow Tables': 'shadow_tables.ipynb'
+    - 'Rough emission': 'rough_emission.ipynb'
   - About: about.md
   - Code Reference: reference/
 
+not_in_nav: |
+  gen_api_pages.py
+
 # Enable math (req. python-markdown-math)
 extra_javascript:
   - docs/javascript/config.js

pyproject.toml

@@ -31,7 +31,6 @@ distributed = "^2022.6.1"
 zenodo-get = "^1.3.4"
 
 [tool.poetry.group.dev.dependencies]
-mkdocs-material = "^6.1.5"
 pytest = "^6.0"
 pytest-cov = "^2.10.1"
 pylint = "^2.6.0"
@@ -45,9 +44,11 @@ spiceypy = "^5.0.1"
 
 [tool.poetry.group.docs.dependencies]
 mkdocs = "^1.4.3"
+mkdocs-material = "^9.0.0"
 mkdocstrings = {extras = ["python"], version = "^0.22.0"}
 mkdocs-gen-files = "^0.5.0"
 mkdocs-literate-nav = "^0.6.0"
+mkdocs-jupyter = "^0.24.2"
 
 
 [tool.poetry.scripts]

roughness/classes.py

@@ -4,6 +4,7 @@
 """
 
 from functools import cached_property
+from pathlib import Path
 import xarray as xr
 from roughness.config import FLOOKUP, TLOOKUP
 import roughness.emission as re
@@ -13,6 +14,11 @@ class RoughnessThermalModel:
     """Initialize a roughness thermophysical model object."""
 
     def __init__(self, shadow_lookup=FLOOKUP, temperature_lookup=TLOOKUP):
+        if shadow_lookup == FLOOKUP and not Path(shadow_lookup).exists():
+            raise FileNotFoundError(
+                "Default shadow lookup table not found. Please run \
+                `roughness -d` in the terminal to download it."
+            )
         self.shadow_lookup = shadow_lookup
         self.temperature_lookup = temperature_lookup
         self.temperature_ds = xr.open_dataset(temperature_lookup)
@@ -21,6 +27,10 @@ def __init__(self, shadow_lookup=FLOOKUP, temperature_lookup=TLOOKUP):
                 f"Temperature lookup {self.temperature_lookup} \
                                must have dimensions az, theta"
             )
+
+    def __repr__(self):
+        return (f"RoughnessThermalModel(shadow_lookup='{self.shadow_lookup}'" +
+                f", temperature_lookup='{self.temperature_lookup}')")
 
     def emission(
         self, sun_theta, sun_az, sc_theta, sc_az, wls, rms, tparams, **kwargs
@@ -29,13 +39,13 @@ def emission(
         Return rough surface emission at the given viewing geometry.
 
         Parameters:
-            sun_theta, sun_az, sc_theta, sc_az: Viewing angles [degrees]
+            sun_theta,sun_az,sc_theta,sc_az (num): Viewing angles [degrees]
                 (incidence, solar_azimuth, emergence, emergence_azimuth)
             wls (arr): Wavelengths [microns]
             rms (arr, optional): RMS roughness [degrees]. Default is 15.
             rerad (bool, optional): If True, include re-radiation from adjacent
                 facets. Default is True.
-            tparams (dict, optional): Dictionary of temperature lookup parameters.
+            tparams (dict, optional): Dictionary of temp erature lookup parameters.
                 Default is None.
             **kwargs