From b1de398804d22822ed8b40d1cd26509680f396d4 Mon Sep 17 00:00:00 2001 From: erexer <13180883+erexer@users.noreply.github.com> Date: Mon, 23 Sep 2024 09:30:56 -0700 Subject: [PATCH 1/4] update docs package versions, migrate from sphinx-pages to sphinx-design --- docs/source/conf.py | 4 +- docs/source/index.rst | 81 +++++++++++++++---------------- docs/source/modules.rst | 2 +- docs/source/tell_quickstarter.rst | 30 ++++++------ pyproject.toml | 6 +-- 5 files changed, 60 insertions(+), 63 deletions(-) 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..d1a429c5 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -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:: 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", From 40826df386f6546b91dfa109b33bbb85a87b2ce6 Mon Sep 17 00:00:00 2001 From: erexer <13180883+erexer@users.noreply.github.com> Date: Tue, 24 Sep 2024 09:27:52 -0700 Subject: [PATCH 2/4] update images --- docs/source/_static/api.svg | 1 - docs/source/_static/cognitive.svg | 1 - docs/source/_static/education.svg | 1 - docs/source/_static/index_api.svg | 97 ++++++++++++++++++++++ docs/source/_static/index_info.svg | 1 + docs/source/_static/index_quickstarter.svg | 66 +++++++++++++++ docs/source/_static/index_user_guide.svg | 67 +++++++++++++++ docs/source/_static/soccer.svg | 1 - docs/source/index.rst | 20 +++-- 9 files changed, 245 insertions(+), 10 deletions(-) delete mode 100644 docs/source/_static/api.svg delete mode 100644 docs/source/_static/cognitive.svg delete mode 100644 docs/source/_static/education.svg create mode 100644 docs/source/_static/index_api.svg create mode 100644 docs/source/_static/index_info.svg create mode 100644 docs/source/_static/index_quickstarter.svg create mode 100644 docs/source/_static/index_user_guide.svg delete mode 100644 docs/source/_static/soccer.svg 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 @@ -api \ 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 @@ -cognitive \ 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 @@ -education \ 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 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + diff --git a/docs/source/_static/index_info.svg b/docs/source/_static/index_info.svg new file mode 100644 index 00000000..09fd08b9 --- /dev/null +++ b/docs/source/_static/index_info.svg @@ -0,0 +1 @@ + \ 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 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + 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 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + 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 @@ -soccer \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index d1a429c5..8fdefcb5 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -29,15 +29,17 @@ 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. -.. grid:: 1 2 2 2 - :gutter: 2 +.. grid:: 4 + :gutter: 3 .. grid-item-card:: Getting started - :img-top: _static/cognitive.svg + :img-top: _static/index_info.svg + :class-img-top: sd-px-4, sd-py-4 :text-align: center New to `tell`? Get familiar with what `tell` is all about. + +++ .. button-ref:: README :click-parent: :color: primary @@ -46,11 +48,13 @@ load models with an explicit spatial resolution component. Getting started .. grid-item-card:: Quickstarter - :img-top: _static/education.svg + :img-top: _static/index_quickstarter.svg + :class-img-top: sd-px-4, sd-py-4 :text-align: center Follow along with this Jupyter notebook to learn the ropes of `tell`. + +++ .. button-ref:: tell_quickstarter :click-parent: :color: primary @@ -59,11 +63,13 @@ load models with an explicit spatial resolution component. Quickstarter .. grid-item-card:: User Guide - :img-top: _static/soccer.svg + :img-top: _static/index_user_guide.svg + :class-img-top: sd-px-4, sd-py-4 :text-align: center The user guide provides in-depth information on the key concepts of `tell`. + +++ .. button-ref:: user_guide :click-parent: :color: primary @@ -72,11 +78,13 @@ load models with an explicit spatial resolution component. User Guide .. grid-item-card:: API reference - :img-top: _static/api.svg + :img-top: _static/index_api.svg + :class-img-top: sd-px-4, sd-py-4 :text-align: center A detailed description of the `tell` API. + +++ .. button-ref:: modules :click-parent: :color: primary From 160751fb619fb5b969d1bbb0fd95fc8d3c8c51a1 Mon Sep 17 00:00:00 2001 From: crvernon Date: Tue, 24 Sep 2024 12:46:29 -0400 Subject: [PATCH 3/4] add custom css to getting started icon --- docs/source/_static/style.css | 11 ++++++++++- docs/source/index.rst | 2 +- 2 files changed, 11 insertions(+), 2 deletions(-) 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/index.rst b/docs/source/index.rst index 8fdefcb5..a1e4bdb6 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -34,7 +34,7 @@ load models with an explicit spatial resolution component. .. grid-item-card:: Getting started :img-top: _static/index_info.svg - :class-img-top: sd-px-4, sd-py-4 + :class-img-top: sd-px-4, sd-py-4 custom-img-size :text-align: center New to `tell`? Get familiar with what `tell` is all about. From 68e612d75c072377222c031eb36f6b8c4f163a3b Mon Sep 17 00:00:00 2001 From: crvernon Date: Tue, 24 Sep 2024 13:00:06 -0400 Subject: [PATCH 4/4] change the icon svg color to match the other icons --- docs/source/_static/index_info.svg | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/source/_static/index_info.svg b/docs/source/_static/index_info.svg index 09fd08b9..c1476387 100644 --- a/docs/source/_static/index_info.svg +++ b/docs/source/_static/index_info.svg @@ -1 +1,12 @@ - \ No newline at end of file + + + + \ No newline at end of file