Merge pull request #255 from blaylockbk/blaylockbk/issue235

Docs: update and fix Sphinx config
blaylockbk · Dec 16, 2023 · 3169577 · 3169577
2 parents 78503e4 + 39a17ee
commit 3169577
Show file tree

Hide file tree

Showing 12 changed files with 313 additions and 279 deletions.
diff --git a/docs/_static/switcher.json b/docs/_static/switcher.json
@@ -9,6 +9,11 @@
         "version": "stable",
         "url": "https://herbie.readthedocs.io/en/stable/"
     },
+    {
+        "name": "2023.12.0",
+        "version": "2023.12.0",
+        "url": "https://herbie.readthedocs.io/en/2023.12.0/"
+    },
     {
         "name": "2023.3.0",
         "version": "2023.3.0",

diff --git a/docs/conf.py b/docs/conf.py
@@ -12,9 +12,11 @@
 #
 import os
 import sys
-import pydata_sphinx_theme
 from datetime import datetime
-import herbie  ## Required to get herbie version and to for accessors to be documented
+
+import pydata_sphinx_theme
+
+import herbie  # # Required to get herbie version and to for accessors to be documented
 
 sys.path.insert(0, os.path.abspath("../.."))
 
@@ -45,6 +47,8 @@
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
+    "sphinx_copybutton",
+    "sphinx.ext.todo",
     "sphinx_design",
     "autodocsumm",
     "sphinx_markdown_tables",
@@ -96,20 +100,9 @@
 # a list of builtin themes.
 #
 html_theme = "pydata_sphinx_theme"
+html_favicon = "_static/logo_new/Herbie-icon.ico"
 
 html_theme_options = {
-    "github_url": "https://github.com/blaylockbk/Herbie",
-    "twitter_url": "https://twitter.com/blaylockbk",
-    "navbar_start": ["navbar-logo"],
-    "navbar_center": ["version-switcher", "navbar-nav"],
-    "navbar_end": ["theme-switcher", "navbar-icon-links.html", "search-field.html"],
-    "switcher": {
-        "json_url": "https://herbie.readthedocs.io/en/latest/_static/switcher.json",
-        "version_match": os.environ.get("READTHEDOCS_VERSION"),
-    },
-    "use_edit_page_button": True,
-    "analytics": {"google_analytics_id": "G-PT9LX1B7B8"},
-    "show_toc_level": 1,
     "external_links": [
         {
             "name": "SynopticPy",
@@ -120,15 +113,43 @@
             "url": "https://goes2go.readthedocs.io/",
         },
     ],
+    "header_links_before_dropdown": 4,
+    "icon_links": [
+        {
+            "name": "Twitter",
+            "url": "https://twitter.com/blaylockbk",
+            "icon": "fa-brands fa-twitter",
+        },
+        {
+            "name": "GitHub",
+            "url": "https://github.com/blaylockbk/Herbie",
+            "icon": "fa-brands fa-github",
+        },
+        {
+            "name": "PyPI",
+            "url": "https://pypi.org/project/herbie-data",
+            "icon": "fa-custom fa-pypi",
+        },
+    ],
     "logo": {
         "image_light": "_static/logo_new/Herbie-logo.png",
         "image_dark": "_static/logo_new/Herbie-logo.png",
     },
+    "use_edit_page_button": True,
+    "show_toc_level": 1,
+    "navbar_align": "left",
+    "show_version_warning_banner": True,
+    "navbar_center": ["version-switcher", "navbar-nav"],
+    "footer_start": ["copyright"],
+    "footer_center": ["sphinx-version"],
+    "switcher": {
+        "json_url": "https://herbie.readthedocs.io/en/latest/_static/switcher.json",
+        "version_match": os.environ.get("READTHEDOCS_VERSION"),
+    },
 }
 
 html_sidebars = {}
 
-html_favicon = "_static/logo_new/Herbie-icon.ico"
 
 html_context = {
     "github_user": "blaylockbk",
@@ -141,16 +162,11 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static", "../images"]
-
-
-fontawesome_included = True
-panels_add_bootstrap_css = False  # False, because pydata theme already loads it
-
 html_css_files = ["css/brian_style.css"]
+html_js_files = []
+todo_include_todos = True
 
-html_js_files = [
-    "https://kit.fontawesome.com/f6cc126dcc.js",
-]
+# ---- Options for autosummary/autodoc output ---------------------------------
 
 # Set autodoc defaults
 autodoc_default_options = {

diff --git a/docs/user_guide/configure.md b/docs/user_guide/configure.md
@@ -17,32 +17,35 @@ overwrite = false
 verbose = true
 ```
 
-The configuration file is mostly a convenience. Any of the configured parameters can be overwritten when creating a new Herbie object. For example,
+The configuration file is mostly a convenience. Any of the configured parameters can be overwritten when creating Herbie objects. For example, this will get the HRRR model and save data to the `~/data` directory, because those are the configured defaults:
 
 ```python
-# This will get the HRRR model and
-# save data to the ~/data folder,
-# because those are the configured defaults:
-Herbie("2023-01-01")
-
-# But you can change the model and the save location
-# when you create a Herbie object.
-# This will change the model to "GFS" and save it in
-# a different location:
-Herbie("2023-01-01", model="gfs", save_dir="/this/folder")
+from herbie import Herbie
+H = Herbie("2023-01-01")
 ```
 
-If Herbie is unable to create its config file, then it will use the defaults.
+But you can set the model and the save location when you create a Herbie object. The following sets a new model (GFS) and will save any downloaded content to the specified location:
 
-If you don't have permission to write to the default location but still want to use a config file, then you can set the a environment variable `HERBIE_CONFIG_PATH` to specify a new path. **Changing the path to the config file is only advised if you don't have permission to write to the default location.**
+```python
+from herbie import Herbie
+H = Herbie("2023-01-01", model="gfs", save_dir="/this/folder")
+```
+
+You might want to set change the default behavior by modifying the Herbie config file if you primarily work with a different model, want to save downloaded content to a different drive, need to use a different source priority, etc.
+
+> If Herbie is unable to create its config file, then it will use the standard defaults.
+
+## Change config file location
+
+If you don't have the right permissions to write to the default location, but you still want to use a config file, then you can set the environment variable `HERBIE_CONFIG_PATH` to specify a new path. **Changing the path to the config file is only advised if you don't have permission to write to the default location.**
 
 ```bash
 export HERBIE_CONFIG_PATH="/my/path/herbie-config/
 ```
 
-## Configurable settings
+# Configurable settings
 
-### `model`
+## `model`
 
 Model name as defined in the [models](https://github.com/blaylockbk/Herbie/tree/main/herbie/models) template folder. CASE INSENSITIVE
 
@@ -56,13 +59,13 @@ Some examples:
 - `'rrfs'` Rapid Refresh Forecast System prototype
 - etc.
 
-### `fxx`
+## `fxx`
 
 Forecast lead time in hours. Available lead times depend on
 the model type and model version. Range is model and run
 dependent.
 
-### `product`
+## `product`
 
 Output variable product file type. If not specified, will
 use first product in model template file. CASE SENSITIVE.
@@ -74,11 +77,11 @@ For example, the HRRR model has these products:
 - `'nat'` native fields
 - `'subh'` subhourly fields
 
-### `member`
+## `member`
 
 Some ensemble models (e.g., GEFS, RRFS) will need to specify an ensemble member number.
 
-### `priority`
+## `priority`
 
 List of data sources in the order of download priority. CASE INSENSITIVE.
 
@@ -99,7 +102,7 @@ For example:
 
 Tip: Look in the `herbie/models` model template files for all the SOURCES available for each model.
 
-### `save_dir`
+## `save_dir`
 
 Location to save GRIB2 files locally. You may use system environment variables like `${HOME}`, and `${TMPDIR}`
 
@@ -109,17 +112,17 @@ This can overwrite the save directory by setting the environment variable `HERBI
 export HERBIE_SAVE_DIR="/my/new/save_dir/
 ```
 
-### `overwrite`
+## `overwrite`
 
 - If `true`, look for GRIB2 file even if local copy exists.
 - If `false`, use the local copy (still need to find the idx file on the remote server).
 
-### `verbose`
+## `verbose`
 
 - If `true`, print info to screen.
 - If `false`, do not print extra info to screen.
 
-## Note: Default Download Priority Rational
+# Note: Default Download Priority Rational
 
 The default download priority is controlled by the order of the SOURCES listed in each model's template file. For example, the [HRRR data sources](https://github.com/blaylockbk/Herbie/blob/main/herbie/models/hrrr.py) are `['aws', 'nomads', 'google', 'azure', 'pando', 'pando2']`. Herbie tries to find the GRIB file at the first source, and then looks at subsequent sources until the file is found. The reason HRRR has this default search order is that I anticipate most often a user will request model output from the recent past or earlier rather than relying on Herbie for operational, real-time needs.
 

diff --git a/docs/user_guide/extend.md b/docs/user_guide/extend.md
@@ -0,0 +1,36 @@
+# 👷🏻‍♂️ Extending Herbie
+
+Herbie can be extended to download additional types of model data from the internet. **_Pull requests are welcome._** The requirements are:
+
+- The NWP model data must exist on an http server.
+- File names must be predictable (i.e., consistent naming with date, model name, forecast lead time, product, etc.)
+- Subetting of a GRIB2 file requires an ASCII index or inventory file (preferablly the wgrib2 style index file).
+
+## Parts of a Herbie Template Class
+
+For an example of what a template class looks like, look at the heavily commented [HRRR template (herbie/models/hrrr.py)](https://github.com/blaylockbk/Herbie/blob/main/herbie/models/hrrr.py).
+
+The model class template function must include the properties
+
+- `DESCRIPTION`: String.
+- `DETAILS`: Dictionary.
+- `PRODUCTS`: Dictionary.
+- `SOURCES`: Dictionary.
+- `LOCALFILE`: Usually set to `f"{self.get_remoteFileName}"`, but not always, if you need to save the file as something else.
+
+The following are optional
+
+- `IDX_SUFFIX` : List of strings. The default is `[".grib2.idx"]`.
+- `IDX_STYLE`: String. Default is `"wgrib2"`. Options: `"wgrib2"` or `"eccodes"`
+
+After creating/editing a model template class, remember to include it in the `herbie/models/__init__.py` file.
+
+## Types of Herbie Template Class
+
+There are two ways to add a custom template to Herbie:
+
+1. **Public Template**: Add a template to the Herbie source code and make a pull request to extend the functionality to Herbie. A model template class must be created and added to `herbie/models` and imported in the `herbie/models/__init__`. Then make a pull request to make your new template available to others 🙂.
+
+2. **Private Template**: To include a template private to yourself, you can add a custom template to the Herbie config directory. You would want to make a private class for locally stored model data or some special handling of public URLs. First, create/edit the file `~/.config/herbie/custom_template.py` and write a template Class. Second, create the empty file `~/.config/herbie/__init__.py`. Herbie will attempt to load these model templates.
+
+> **Special Case for local model data:** If you have model data stored locally, such as from a WRF simulation, and you have an index file accompanying each GRIB2 file, you can use Herbie to subset the data and open it with xarray. Follow the [local.py](https://github.com/blaylockbk/Herbie/blob/main/herbie/models/local.py) template to create a custom class using the Private template method described.
diff --git a/docs/user_guide/extend.rst b/docs/user_guide/extend.rst