Merge pull request #1190 from PCMDI/clean_up_doc

lee1043 · web-flow · commit 450105055907 · 2024-11-18T14:36:38.000-08:00
Clean up doc
diff --git a/.github/workflows/build_workflow.yml b/.github/workflows/build_workflow.yml
@@ -54,16 +54,15 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Set up Conda Environment
-        uses: conda-incubator/setup-miniconda@v2
+        uses: conda-incubator/setup-miniconda@v3
         with:
-          activate-environment: "pcmdi_metrics_ci"
-          miniforge-variant: Mambaforge
+          miniforge-variant: Miniforge3
           miniforge-version: latest
+          activate-environment: "pcmdi_metrics_ci"
           environment-file: conda-env/ci.yml
-          use-mamba: true
-          mamba-version: "*"
           channel-priority: strict
           auto-update-conda: true
+          python-version: ${{ matrix.python-version }}
 
       # Used for refreshing the cache every 24 hours to avoid inconsistencies of package
       # versions between the CI pipeline and local installations.
@@ -79,7 +78,7 @@ jobs:
           key:
             conda-${{ runner.os }}--${{ runner.arch }}--${{
             steps.get-date.outputs.today }}-${{
-            hashFiles('conda-env/dev.yml') }}-${{ env.CACHE_NUMBER}}
+            hashFiles('conda-env/ci.yml') }}-${{ env.CACHE_NUMBER}}
         env:
           # Increase this value to reset cache if conda/dev.yml has not changed in the workflow
           CACHE_NUMBER: 0
@@ -118,10 +117,10 @@ jobs:
         with:
           path: ~/conda_pkgs_dir
           key: ${{ runner.os }}-conda-${{ env.CACHE_NUMBER }}-${{
-            hashFiles('conda-env/ci.yml') }}
+            hashFiles('conda-env/dev.yml') }}
 
       - name: Set up Conda Environment
-        uses: conda-incubator/setup-miniconda@v2
+        uses: conda-incubator/setup-miniconda@v3
         with:
           activate-environment: "pcmdi_metrics_dev"
           miniforge-variant: Miniforge3
diff --git a/doc/jupyter/Demo/Demo_0_download_data.ipynb b/doc/jupyter/Demo/Demo_0_download_data.ipynb
@@ -8,7 +8,7 @@
     "\n",
     "Download sample data and set up parameter files\n",
     "\n",
-    "This Notebook sets up the data for the other demos. It is recommended that you run this and other demos in a conda environment with **xcdat** and **pcmdi_metrics** installed."
+    "This Notebook sets up the data for the other demos. It is recommended that you run this and other demos in a conda environment with **xcdat** and **pcmdi_metrics** installed. The files to download are listed in https://pcmdiweb.llnl.gov/pss/pmpdata/pmp_tutorial_files.v20240201.txt."
    ]
   },
   {
@@ -52,7 +52,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "In below cell, you are going to download sample input files from PCMDI server. The total size of dataset is about 2 GB, and so please be aware that downloading will take some time to complete. List of downloading files can be found in [`data_files.txt`](https://pcmdiweb.llnl.gov/pss/pmpdata/pmp_tutorial_files.v20240201.txt) file."
+    "In below cell, you are going to download sample input files from PCMDI server. The total size of dataset is about 2 GB, and so please be aware that downloading will take some time to complete."
    ]
   },
   {
diff --git a/doc/jupyter/Demo/Demo_5_mjo_metrics.ipynb b/doc/jupyter/Demo/Demo_5_mjo_metrics.ipynb
@@ -391,13 +391,6 @@
     "from IPython.display import Image\n",
     "Image(filename=demo_output_directory+\"/mjo/Ex2/cmip5_GISS-E2-H_historical_r6i1p1_mjo_2000-2005_NDJFMA_cmmGrid.png\")"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {
diff --git a/doc/jupyter/Demo/Demo_7_precip_variability.ipynb b/doc/jupyter/Demo/Demo_7_precip_variability.ipynb
@@ -889,13 +889,6 @@
     "    metric = json.load(f)[\"RESULTS\"]\n",
     "print(json.dumps(metric, indent=2))"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {
diff --git a/doc/jupyter/Demo/Demo_8_extremes.ipynb b/doc/jupyter/Demo/Demo_8_extremes.ipynb
@@ -2242,14 +2242,6 @@
     "%%bash -s \"$demo_output_directory\"\n",
     "rm -r $1/extremes_tmp"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "e8ff050a",
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {
diff --git a/doc/jupyter/Demo/Demo_9_seaIceExtent_ivanova.ipynb b/doc/jupyter/Demo/Demo_9_seaIceExtent_ivanova.ipynb
@@ -3013,14 +3013,6 @@
     "<a href=Demo_9_seaIceExtent_ivanova.ipynb#top>Go back to Top</a>\n",
     "</div>"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "e3b50c5e",
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {
diff --git a/docs/demo-notebooks.rst b/docs/demo-notebooks.rst
@@ -54,8 +54,8 @@ Basic Usage Examples
    examples/parallel_coordinate_plot_example
    examples/taylor_diagram_example
 
-Real World Use Cases
-^^^^^^^^^^^^^^^^^^^^
+Practical Use Cases
+^^^^^^^^^^^^^^^^^^^
 
 .. nbgallery::
 
@@ -65,4 +65,5 @@ Real World Use Cases
    examples/parallel_coordinate_plot_mean_clim_multiMIPs
    examples/taylor_diagram_multiple_CMIPs
    examples/mean_clim_plots_test_model
-   examples/variability_modes_plots_all-stats
+   examples/variability_modes_plots_all-stats
+   examples/return_value_portrait_plot_demo
diff --git a/docs/index.rst b/docs/index.rst
@@ -81,28 +81,28 @@ BSD 3-Clause License. See `LICENSE <https://github.com/PCMDI/pcmdi_metrics/blob/
 .. toctree::
    :maxdepth: 1
    :hidden:
-   :caption: For users:
+   :caption: For users
 
    overview
    start
    metrics
    demo-notebooks
-   Results <https://pcmdi.llnl.gov/research/metrics/>
 
 .. toctree::
    :maxdepth: 1
    :hidden:
-   :caption: For developers/contributors:
+   :caption: For developers/contributors
 
    api
    contributing
    resources
    team
-   GitHub repository <https://github.com/PCMDI/pcmdi_metrics>
 
 .. toctree::
    :maxdepth: 1
    :hidden:
-   :caption: Community
+   :caption: Links
 
-   GitHub discussions <https://github.com/PCMDI/pcmdi_metrics/discussions>
+   PMP Results <https://pcmdi.llnl.gov/research/metrics/>
+   Source Code <https://github.com/PCMDI/pcmdi_metrics>
+   Discussions <https://github.com/PCMDI/pcmdi_metrics/discussions>
diff --git a/docs/metrics_enso.rst b/docs/metrics_enso.rst
@@ -39,4 +39,4 @@ Additional Resources
 .. _Description for the results: https://pcmdi.llnl.gov/metrics/enso/
 .. _Description for included metrics: https://github.com/CLIVAR-PRP/ENSO_metrics/wiki
 .. _Interactive graphics for PMP-calculated ENSO Metrics: https://pcmdi.llnl.gov/pmp-preliminary-results/interactive_plot/portrait_plot/enso_metric/enso_metrics_interactive_portrait_plots_v20210723.html
-.. _PMP demo Jupyter notebook: https://github.com/PCMDI/pcmdi_metrics/blob/main/doc/jupyter/Demo/Demo_6_ENSO.ipynb
+.. _PMP demo Jupyter notebook: examples/Demo_6_ENSO.html
diff --git a/docs/metrics_ext.rst b/docs/metrics_ext.rst
@@ -13,11 +13,11 @@ Demo
 =====
 * `PMP demo Jupyter notebook`_
 
-.. _PMP demo Jupyter notebook: https://github.com/PCMDI/pcmdi_metrics/blob/main/doc/jupyter/Demo/Demo_8_extremes.ipynb
+.. _PMP demo Jupyter notebook: examples/Demo_8_extremes.html
 
 * `Extremes Portrait Plot demo Jupyter notebook`_
 
-.. _Extremes Portrait Plot demo Jupyter notebook: https://github.com/PCMDI/pcmdi_metrics/blob/main/pcmdi_metrics/graphics/portrait_plot/return_value_portrait_plot_demo.ipynb
+.. _Extremes Portrait Plot demo Jupyter notebook: examples/return_value_portrait_plot_demo
 
 Inputs
 ========
diff --git a/docs/metrics_mean-clim.rst b/docs/metrics_mean-clim.rst
@@ -20,8 +20,7 @@ Before it can be applied some preparation is needed including:
 * Construction of an input parameter file to run the desired operations  
 
 
-Each of these steps is included in the 
-`mean climate notebook <https://github.com/PCMDI/pcmdi_metrics/blob/master/doc/jupyter/Demo/Demo_1_mean_climate.ipynb>`_ 
+Each of these steps is included in the following demo notebooks
 along with a series of examples that demonstrate the options. 
 These steps are also summarized below.
 
@@ -110,6 +109,6 @@ In addition to the minimum set of parameters noted above, the following **additi
 * **save_test_clims** Select to save (or not) interpolated climatologies including masking
 * **case_id** Save JSON and netCDF files into a subdirectory so that results from multiple tests can be readily organized
  
-.. _PMP demo Jupyter notebook1a: https://github.com/PCMDI/pcmdi_metrics/blob/main/doc/jupyter/Demo/Demo_1a_compute_climatologies.ipynb
-.. _PMP demo Jupyter notebook1b: https://github.com/PCMDI/pcmdi_metrics/blob/main/doc/jupyter/Demo/Demo_1b_mean_climate.ipynb
+.. _PMP demo Jupyter notebook1a: examples/Demo_1a_compute_climatologies.html
+.. _PMP demo Jupyter notebook1b: examples/Demo_1b_mean_climate.html
 
diff --git a/docs/metrics_mjo.rst b/docs/metrics_mjo.rst
@@ -56,6 +56,6 @@ References
 .. _1972: https://doi.org/10.1175/1520-0469(1972)029%3C1109:DOGSCC%3E2.0.CO;2
 .. _1994: https://doi.org/10.1175/1520-0493(1994)122%3C0814:OOTDTO%3E2.0.CO;2
 
-.. _PMP demo Jupyter notebook: https://github.com/PCMDI/pcmdi_metrics/blob/main/doc/jupyter/Demo/Demo_5_mjo_metrics.ipynb
+.. _PMP demo Jupyter notebook: examples/Demo_5_mjo_metrics.html
 .. _Interactive graphics for PMP-calculated MJO Metrics: https://pcmdi.llnl.gov/pmp-preliminary-results/interactive_plot/mjo/bar_chart/mjo_ewr_cmip5and6_overlap_runs_average_v20200720.html
 .. _Description for the results: https://pcmdi.llnl.gov/research/metrics/mjo/
diff --git a/docs/metrics_monsoon.rst b/docs/metrics_monsoon.rst
@@ -21,5 +21,5 @@ References
 ==========
 * Sperber, K.R. and Annamalai, H., 2014. The use of fractional accumulated precipitation for the evaluation of the annual cycle of monsoons. Climate Dynamics, 43, 3219-3244, doi:10.1007/s00382-014-2099-3
 
-.. _PMP demo Jupyter notebook: https://github.com/PCMDI/pcmdi_metrics/blob/main/doc/jupyter/Demo/Demo_2b_monsoon_sperber.ipynb
+.. _PMP demo Jupyter notebook: examples/Demo_2b_monsoon_sperber.html
 
diff --git a/docs/metrics_mov.rst b/docs/metrics_mov.rst
@@ -40,6 +40,6 @@ References
 * Lee, J., K. Sperber, P. Gleckler, K. Taylor, and C. Bonfils, 2021: Benchmarking performance changes in the simulation of extratropical modes of variability across CMIP generations. Journal of Climate, 34, 6945–6969, https://doi.org/10.1175/JCLI-D-20-0832.1
 
 
-.. _PMP demo Jupyter notebook: https://github.com/PCMDI/pcmdi_metrics/blob/main/doc/jupyter/Demo/Demo_4_modes_of_variability.ipynb
+.. _PMP demo Jupyter notebook: examples/Demo_4_modes_of_variability.html
 .. _Interactive graphics for PMP-calculated MoV Metrics: https://pcmdi.llnl.gov/pmp-preliminary-results/interactive_plot/variability_modes/portrait_plot/pmp_mov_page_viewer.html
 .. _Description for the results: https://pcmdi.llnl.gov/research/metrics/variability_modes/
diff --git a/docs/metrics_precip-variability.rst b/docs/metrics_precip-variability.rst
@@ -95,6 +95,6 @@ Reference
 Ahn, M.-S., P. J. Gleckler, J. Lee, A. G. Pendergrass, and C. Jakob, 2022: Benchmarking Simulated Precipitation Variability Amplitude across Timescales. Journal of Climate. https://doi.org/10.1175/JCLI-D-21-0542.1
 
 
-.. _PMP demo Jupyter notebook: https://github.com/PCMDI/pcmdi_metrics/blob/main/doc/jupyter/Demo/Demo_7_precip_variability.ipynb
+.. _PMP demo Jupyter notebook: examples/Demo_7_precip_variability.html
 .. _this link: https://github.com/PCMDI/pcmdi_metrics/tree/main/pcmdi_metrics/precip_variability/param
 .. _calc_ratio.py: https://github.com/PCMDI/pcmdi_metrics/blob/main/pcmdi_metrics/precip_variability/scripts_pcmdi/calc_ratio.py
diff --git a/docs/metrics_sea_ice.rst b/docs/metrics_sea_ice.rst
@@ -13,7 +13,7 @@ Demo
 =====
 * `PMP demo Jupyter notebook`_
 
-.. _PMP demo Jupyter notebook: https://github.com/PCMDI/pcmdi_metrics/blob/main/doc/jupyter/Demo/Demo_9_seaIceExtent_ivanova.ipynb
+.. _PMP demo Jupyter notebook: examples/Demo_9_seaIceExtent_ivanova.html
 
 Inputs
 ======
diff --git a/docs/metrics_subdaily-precipitation.rst b/docs/metrics_subdaily-precipitation.rst
@@ -26,4 +26,4 @@ References
 
 
 
-.. _PMP demo Jupyter notebook: https://github.com/PCMDI/pcmdi_metrics/blob/main/doc/jupyter/Demo/Demo_3_diurnal_cycle.ipynb
+.. _PMP demo Jupyter notebook: examples/Demo_3_diurnal_cycle.html

Original file line number	Diff line number	Diff line change
`@@ -8,7 +8,7 @@`
`8`	`8`	`"\n",`
`9`	`9`	`"Download sample data and set up parameter files\n",`
`10`	`10`	`"\n",`
`11`		`- "This Notebook sets up the data for the other demos. It is recommended that you run this and other demos in a conda environment with xcdat and pcmdi_metrics installed."`
	`11`	`+ "This Notebook sets up the data for the other demos. It is recommended that you run this and other demos in a conda environment with xcdat and pcmdi_metrics installed. The files to download are listed in https://pcmdiweb.llnl.gov/pss/pmpdata/pmp_tutorial_files.v20240201.txt."`
`12`	`12`	`]`
`13`	`13`	`},`
`14`	`14`	`{`
`@@ -52,7 +52,7 @@`
`52`	`52`	`"cell_type": "markdown",`
`53`	`53`	`"metadata": {},`
`54`	`54`	`"source": [`
`55`		- "In below cell, you are going to download sample input files from PCMDI server. The total size of dataset is about 2 GB, and so please be aware that downloading will take some time to complete. List of downloading files can be found in [`data_files.txt`](https://pcmdiweb.llnl.gov/pss/pmpdata/pmp_tutorial_files.v20240201.txt) file."
	`55`	`+ "In below cell, you are going to download sample input files from PCMDI server. The total size of dataset is about 2 GB, and so please be aware that downloading will take some time to complete."`
`56`	`56`	`]`
`57`	`57`	`},`
`58`	`58`	`{`
Original file line number	Diff line number	Diff line change
`@@ -391,13 +391,6 @@`
`391`	`391`	`"from IPython.display import Image\n",`
`392`	`392`	`"Image(filename=demo_output_directory+\"/mjo/Ex2/cmip5_GISS-E2-H_historical_r6i1p1_mjo_2000-2005_NDJFMA_cmmGrid.png\")"`
`393`	`393`	`]`
`394`		`- },`
`395`		`- {`
`396`		`- "cell_type": "code",`
`397`		`- "execution_count": null,`
`398`		`- "metadata": {},`
`399`		`- "outputs": [],`
`400`		`- "source": []`
`401`	`394`	`}`
`402`	`395`	`],`
`403`	`396`	`"metadata": {`
Original file line number	Diff line number	Diff line change
`@@ -889,13 +889,6 @@`
`889`	`889`	`" metric = json.load(f)[\"RESULTS\"]\n",`
`890`	`890`	`"print(json.dumps(metric, indent=2))"`
`891`	`891`	`]`
`892`		`- },`
`893`		`- {`
`894`		`- "cell_type": "code",`
`895`		`- "execution_count": null,`
`896`		`- "metadata": {},`
`897`		`- "outputs": [],`
`898`		`- "source": []`
`899`	`892`	`}`
`900`	`893`	`],`
`901`	`894`	`"metadata": {`