diff --git a/docs/source/_static/api.svg b/docs/source/_static/api.svg
deleted file mode 100644
index 4f234132..00000000
--- a/docs/source/_static/api.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/source/_static/cognitive.svg b/docs/source/_static/cognitive.svg
deleted file mode 100644
index dc8f670e..00000000
--- a/docs/source/_static/cognitive.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/source/_static/education.svg b/docs/source/_static/education.svg
deleted file mode 100644
index 5f5c20d2..00000000
--- a/docs/source/_static/education.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/source/_static/index_api.svg b/docs/source/_static/index_api.svg
new file mode 100644
index 00000000..70bf0d35
--- /dev/null
+++ b/docs/source/_static/index_api.svg
@@ -0,0 +1,97 @@
+
+
+
+
diff --git a/docs/source/_static/index_info.svg b/docs/source/_static/index_info.svg
new file mode 100644
index 00000000..c1476387
--- /dev/null
+++ b/docs/source/_static/index_info.svg
@@ -0,0 +1,12 @@
+
\ No newline at end of file
diff --git a/docs/source/_static/index_quickstarter.svg b/docs/source/_static/index_quickstarter.svg
new file mode 100644
index 00000000..d00e4624
--- /dev/null
+++ b/docs/source/_static/index_quickstarter.svg
@@ -0,0 +1,66 @@
+
+
+
+
diff --git a/docs/source/_static/index_user_guide.svg b/docs/source/_static/index_user_guide.svg
new file mode 100644
index 00000000..a567103a
--- /dev/null
+++ b/docs/source/_static/index_user_guide.svg
@@ -0,0 +1,67 @@
+
+
+
+
diff --git a/docs/source/_static/soccer.svg b/docs/source/_static/soccer.svg
deleted file mode 100644
index 8f5dc8ad..00000000
--- a/docs/source/_static/soccer.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/source/_static/style.css b/docs/source/_static/style.css
index d4da7a5c..be49cb1c 100644
--- a/docs/source/_static/style.css
+++ b/docs/source/_static/style.css
@@ -45,4 +45,13 @@
.card-body {
padding: 0.5rem;
-}
\ No newline at end of file
+}
+
+/* Custom class for resizing grid-item-card images */
+.custom-img-size {
+ width: 75px; /* Set desired width */
+ height: auto; /* Maintain aspect ratio */
+ max-width: 100%; /* Ensure responsiveness */
+ display: block; /* Remove inline spacing */
+ margin: 0 auto; /* Center the image horizontally */
+}
diff --git a/docs/source/conf.py b/docs/source/conf.py
index eba49574..c516e183 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -36,12 +36,14 @@
'sphinx.ext.autosummary',
'sphinx.ext.napoleon',
'sphinx.ext.viewcode',
- 'sphinx_panels',
+ 'sphinx_design',
'sphinx_rtd_theme',
'sphinx.ext.githubpages',
'sphinx.ext.mathjax',
]
+pygments_style = 'sphinx'
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 6f5acfa7..a1e4bdb6 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -29,65 +29,68 @@ accurate load forecasting (electric utilities, regulatory commissions, industria
researchers interested in energy system transitions, and many others in need of a framework for blending short and long-term
load models with an explicit spatial resolution component.
-.. panels::
- :card: + intro-card text-center
- :column: col-lg-6 col-md-6 col-sm-6 col-xs-12 d-flex
+.. grid:: 4
+ :gutter: 3
- >>>
- :img-top: _static/cognitive.svg
+ .. grid-item-card:: Getting started
+ :img-top: _static/index_info.svg
+ :class-img-top: sd-px-4, sd-py-4 custom-img-size
+ :text-align: center
- Getting started
- ^^^
+ New to `tell`? Get familiar with what `tell` is all about.
- New to `tell`? Get familiar with what `tell` is all about.
+ +++
+ .. button-ref:: README
+ :click-parent:
+ :color: primary
+ :expand:
- +++
- .. link-button:: README
- :type: ref
- :text: Getting started
- :classes: btn-block btn-secondary stretched-link
+ Getting started
- >>>
- :img-top: _static/education.svg
+ .. grid-item-card:: Quickstarter
+ :img-top: _static/index_quickstarter.svg
+ :class-img-top: sd-px-4, sd-py-4
+ :text-align: center
- Quickstarter
- ^^^
+ Follow along with this Jupyter notebook to learn the ropes of `tell`.
- Follow along with this Jupyter notebook to learn the ropes of `tell`.
+ +++
+ .. button-ref:: tell_quickstarter
+ :click-parent:
+ :color: primary
+ :expand:
- +++
- .. link-button:: tell_quickstarter
- :type: ref
- :text: Quickstarter
- :classes: btn-block btn-secondary stretched-link
+ Quickstarter
- >>>
- :img-top: _static/soccer.svg
+ .. grid-item-card:: User Guide
+ :img-top: _static/index_user_guide.svg
+ :class-img-top: sd-px-4, sd-py-4
+ :text-align: center
- User Guide
- ^^^
+ The user guide provides in-depth information on the key concepts of `tell`.
- The user guide provides in-depth information on the key concepts of `tell`.
+ +++
+ .. button-ref:: user_guide
+ :click-parent:
+ :color: primary
+ :expand:
- +++
- .. link-button:: user_guide
- :type: ref
- :text: User Guide
- :classes: btn-block btn-secondary stretched-link
+ User Guide
- >>>
- :img-top: _static/api.svg
+ .. grid-item-card:: API reference
+ :img-top: _static/index_api.svg
+ :class-img-top: sd-px-4, sd-py-4
+ :text-align: center
- API reference
- ^^^
+ A detailed description of the `tell` API.
- A detailed description of the `tell` API.
+ +++
+ .. button-ref:: modules
+ :click-parent:
+ :color: primary
+ :expand:
- +++
- .. link-button:: modules
- :type: ref
- :text: API
- :classes: btn-block btn-secondary stretched-link
+ API
.. toctree::
diff --git a/docs/source/modules.rst b/docs/source/modules.rst
index f43e56ed..e844fad1 100644
--- a/docs/source/modules.rst
+++ b/docs/source/modules.rst
@@ -1,5 +1,5 @@
API Reference
-====
+=============
.. toctree::
:maxdepth: 4
diff --git a/docs/source/tell_quickstarter.rst b/docs/source/tell_quickstarter.rst
index adeeed8b..015173ea 100644
--- a/docs/source/tell_quickstarter.rst
+++ b/docs/source/tell_quickstarter.rst
@@ -62,7 +62,7 @@ supported by GeoPandas functionality. Please see suggestions for installing
GeoPandas on Windows here:
https://geopandas.org/en/stable/getting_started/install.html)
-.. code:: ipython3
+.. code:: python
# Start by importing the TELL package and information about your operating system:
import os
@@ -85,7 +85,7 @@ available in a `Zenodo data
package `__. The sample
forcing data package will require ~250 MB of storage.
-.. code:: ipython3
+.. code:: python
# Identify the current working directory, the subdirectory where the data will be stored, and the image output subdirectory:
current_dir = os.path.join(os.path.dirname(os.getcwd()))
@@ -101,13 +101,13 @@ forcing data package will require ~250 MB of storage.
os.makedirs(tell_image_dir)
-.. code:: ipython3
+.. code:: python
# Download the TELL quickstarter data package from Zenodo:
tell.install_quickstarter_data(data_dir = tell_data_dir)
-.. code:: ipython3
+.. code:: python
# Download the TELL sample forcing data package from Zenodo:
tell.install_sample_forcing_data(data_dir = tell_data_dir)
@@ -146,13 +146,13 @@ a function to do some basic analysis of the trained model’s performance.
More extensive evaluation of the ``tell`` predictive models is included
in the ``tell_mlp_calibration_evaluation.ipynb`` notebook.
-.. code:: ipython3
+.. code:: python
# For more information about the training of predictive models you can call the help function:
help(tell.train)
-.. code:: ipython3
+.. code:: python
# Run the MLP training step for a single BA (i.e., "region"):
prediction_df, validation_df = tell.train(region = 'PJM',
@@ -169,7 +169,7 @@ You can also train multiple BAs at the same time using parallel
processing. The example code block below retrains the models for all BAs
in ``tell``.
-.. code:: ipython3
+.. code:: python
# Generate a list of BA abbreviations to process:
ba_abbrev_list = tell.get_balancing_authority_to_model_dict().keys()
@@ -183,7 +183,7 @@ in ``tell``.
validation_df
-.. code:: ipython3
+.. code:: python
# Plot the statistical performance (e.g., RMS_ABS, RMS_NORM, MAPE, or R2) of the predictive models across all the BAs in TELL:
tell.plot_mlp_summary_statistics(validation_df,
@@ -203,7 +203,7 @@ meteorology for each BA: 2039, 2059, 2079, and 2099. Those are the only
valid options for the ``year`` variable when calling the prediciton
functions.
-.. code:: ipython3
+.. code:: python
# Run the MLP prediction step for a single BA (i.e., "region"):
pdf = tell.predict(region = 'ERCO',
@@ -217,7 +217,7 @@ functions.
pdf
-.. code:: ipython3
+.. code:: python
# Generate a list of BA abbreviations to process:
ba_abbrev_list = tell.get_balancing_authority_to_model_dict().keys()
@@ -250,7 +250,7 @@ since it takes a while to write out the county-level output data this
output is optional. To output county-level load projections just set the
``save_county_data`` flag to true.
-.. code:: ipython3
+.. code:: python
# Run the TELL model forward in time for a given year:
summary_df, ba_time_series_df, state_time_series_df = tell.execute_forward(year_to_process = '2039',
@@ -276,7 +276,7 @@ and ``tell``. The data plotted here are in units of TWh and the ``tell``
values are the unscaled projections. The scaled projections ``tell`` are
by definition equal to those from GCAM-USA.
-.. code:: ipython3
+.. code:: python
# Plot the annual total loads from both GCAM-USA and TELL:
tell.plot_state_annual_total_loads(year_to_plot = '2039',
@@ -294,7 +294,7 @@ Here we plot time-series of the raw (unscaled) and scaled total loads
from ``tell`` at the state level. The user specifies which state they
want to plot using the \`state_to_plot” variable in the function call.
-.. code:: ipython3
+.. code:: python
# Plot the time-series of raw and scaled loads from TELL at the state level for a user-specified state:
tell.plot_state_load_time_series(state_to_plot = 'Connecticut',
@@ -314,7 +314,7 @@ the frequency at which a given load occurs in a state. The user
specifies which state they want to plot using the “state_to_plot”
variable in the function call.
-.. code:: ipython3
+.. code:: python
# Plot the load duration curve at the state level for a user-specified state:
tell.plot_state_load_duration_curve(state_to_plot = 'North Carolina',
@@ -334,7 +334,7 @@ scaled total loads from ``tell`` at the BA level. The user specifies
which BA they want to plot using the “ba_to_plot” variable in the
function call.
-.. code:: ipython3
+.. code:: python
# Plot the time-series of raw and scaled loads from TELL at the BA level for a user-specified BA (e.g., PJM, CISO, ERCO, etc.):
tell.plot_ba_load_time_series(ba_to_plot = 'NYIS',
diff --git a/pyproject.toml b/pyproject.toml
index 85aad733..f0c6a1b4 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -80,9 +80,9 @@ docs = [
"nbsphinx>=0.8.6",
"recommonmark>=0.7.1",
"setuptools>=57.0.0",
- "sphinx>=4.0.2",
- "sphinx-panels>=0.6.0",
- "sphinx-rtd-theme>=1.0.0",
+ "sphinx<8,>=6",
+ "sphinx-design>=0.6.1",
+ "sphinx-rtd-theme>=2.0.0",
]
deploy = [
"twine>=3.4.1",