Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

update docs package versions, migrate from sphinx-pages to sphinx-design #61

Merged
merged 4 commits into from
Sep 24, 2024
Merged

update docs package versions, migrate from sphinx-pages to sphinx-design #61

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b1de398
update docs package versions, migrate from sphinx-pages to sphinx-design
erexer Sep 23, 2024
40826df
update images
erexer Sep 24, 2024
160751f
add custom css to getting started icon
crvernon Sep 24, 2024
68e612d
change the icon svg color to match the other icons
crvernon Sep 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/source/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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']

Expand Down
81 changes: 38 additions & 43 deletions docs/source/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,65 +29,60 @@ 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:: 1 2 2 2
:gutter: 2

>>>
:img-top: _static/cognitive.svg
.. grid-item-card:: Getting started
:img-top: _static/cognitive.svg
: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/education.svg
: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/soccer.svg
: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/api.svg
: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::
Expand Down
2 changes: 1 addition & 1 deletion docs/source/modules.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
API Reference
====
=============

.. toctree::
:maxdepth: 4
Expand Down
30 changes: 15 additions & 15 deletions docs/source/tell_quickstarter.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -85,7 +85,7 @@ available in a `Zenodo data
package <https://zenodo.org/record/6354665#.Yi-_PRDMJTY>`__. 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()))
Expand All @@ -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)
Expand Down Expand Up @@ -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',
Expand All @@ -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()
Expand All @@ -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,
Expand All @@ -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',
Expand All @@ -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()
Expand Down Expand Up @@ -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',
Expand All @@ -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',
Expand All @@ -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',
Expand All @@ -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',
Expand All @@ -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',
Expand Down
6 changes: 3 additions & 3 deletions pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down