From 9202224ba337a1db20d7307d1edd73e5eda6a2df Mon Sep 17 00:00:00 2001 From: Teagan King Date: Thu, 17 Oct 2024 09:29:51 -0600 Subject: [PATCH 1/5] documentation updates --- README.md | 5 ++-- docs/ContributorsGuide.rst | 2 ++ docs/Contributors_Guide.md | 24 +++++++++++++++++++ docs/addingnotebookstocollection.md | 8 ++++++- docs/conf.py | 4 ++-- ...ributors.rst => contributors_to_cupid.rst} | 0 docs/index.rst | 3 ++- 7 files changed, 39 insertions(+), 7 deletions(-) create mode 100644 docs/ContributorsGuide.rst create mode 100644 docs/Contributors_Guide.md rename docs/{contributors.rst => contributors_to_cupid.rst} (100%) diff --git a/README.md b/README.md index 668ac8b..7832710 100644 --- a/README.md +++ b/README.md @@ -44,11 +44,10 @@ If you do not have `mamba` installed, you can still use `conda`... it will just $ pip install -e . # installs cupid ``` +1. Run `pre-commit install` to configure `git` to automatically run `pre-commit` checks when you try to commit changes; the commit will only proceed if all checks pass. Note that CUPiD uses `pre-commit` to ensure code formatting guidelines are followed, and pull requests will not be accepted if they fail the `pre-commit`-based Github Action. 1. If you plan on contributing code to CUPiD, whether developing CUPiD itself or providing notebooks for CUPiD to run, -please see the [Contributer's Guide](https://github.com/NCAR/CUPiD/wiki/Contributor's-Guide). -Note that CUPiD uses `pre-commit` to ensure code formatting guidelines are followed, -and pull requests will not be accepted if they fail the `pre-commit`-based Github Action. +please see the [Contributor's Guide](https://ncar.github.io/CUPiD/ContributorsGuide.html). ## Running diff --git a/docs/ContributorsGuide.rst b/docs/ContributorsGuide.rst new file mode 100644 index 0000000..69c2120 --- /dev/null +++ b/docs/ContributorsGuide.rst @@ -0,0 +1,2 @@ +.. include:: Contributors_Guide.md + :parser: myst diff --git a/docs/Contributors_Guide.md b/docs/Contributors_Guide.md new file mode 100644 index 0000000..9761c34 --- /dev/null +++ b/docs/Contributors_Guide.md @@ -0,0 +1,24 @@ +# Welcome to the CUPiD Contributor's Guide! + +Now that your repository is set up, if you would like to add a diagnostics notebook, you can follow the [guide to adding diagnostics notebooks](https://ncar.github.io/CUPiD/addingnotebookstocollection.html). + +In order to contribute code to this repository, we recommend that you get started with these steps: + +0. [Open an issue](https://github.com/NCAR/CUPiD/issues) prior to development +1. Set up git and make an account if needed. +2. Create your personal fork of the repository by going to the [CUPiD repository](https://github.com/NCAR/CUPiD) and clicking the `Fork` button. Clone your personal repository by going to your forked repository, clicking the green `Code` button, and then, in your terminal, run `git clone --recurse-submodules https://github.com//CUPiD` +3. Check out a new branch with a name that is relevant to the changes you want to make: `git checkout -b ` +4. [Install CUPiD](https://ncar.github.io/CUPiD/index.html#installing), relevant environments, and setup `pre-commit`. +5. Make your edits and add your name to our `contributors.md` file to make sure we recognize your contributions +6. Merge in recent changes from master +7. Ensure that `pre-commit` checks all pass +8. IF updating `github.io` pages, test with the steps listed below, otherwise proceed to #9: + - Create the environment necessary for building documentation with `$ conda env create -f environments/docs.yml` + - Activate the docs environment: `$ conda activate cupid-docs` + - Change into the `docs` directory: `$ cd docs` + - Build the documentation: `$ make html` + - View the documentation to make sure it rendered correctly: `$ open _build/html/index.html` +9. Submit a Pull Request +10. Await review +11. Update PR with any requested changes +12. Repository admins will merge the PR diff --git a/docs/addingnotebookstocollection.md b/docs/addingnotebookstocollection.md index c4bee82..c091115 100644 --- a/docs/addingnotebookstocollection.md +++ b/docs/addingnotebookstocollection.md @@ -2,6 +2,7 @@ Generally, a good fit for a diagnostic notebook is one that reads in CESM output, does some processing, and outputs plots, values, and/or new files (images, data, etc.) that are useful for evaluating the run. +0. Check out our [Contributor's Guide](https://ncar.github.io/CUPiD/ContributorsGuide.html) to make ensure appropriate setup of your git repository for contributions. 1. Install the `environments/cupid-analysis.yml` environment (see [installation instructions](https://ncar.github.io/CUPiD/index.html#installing)). Make sure that your notebook runs properly in this environment. If there are conflicts or missing dependencies, open an issue or talk to CUPiD developers so we can find a solution. 2. In your notebook, move all variables you might want to change (paths to data, dates to select, etc.) to a cell near the top. For example: @@ -40,4 +41,9 @@ Generally, a good fit for a diagnostic notebook is one that reads in CESM output 7. Update your parameters. Parameters that are specific to just this notebook should go under `parameter_groups` in the notebook's entry under `compute_notebooks`. Global parameters that you want passed in to every notebook in the collection should go under `global_params`. When `CUPiD` executes your notebook, all of these parameters will get put in a new cell below the cell tagged `parameters` that you added in step 3. This means they will supercede the values of the parameters that you put in the cell above---the names, notation, etc. should match to make sure your notebook is able to find the variables it needs. -8. All set! Your collection can now be run and built with `cupid-run` and `cupid-build` as usual. +8. Your collection can now be run and built with `cupid-run` and `cupid-build` as usual. + +9. If you're happy with your notebook and want to add it to the CUPiD repository, there are a few formatting items that we would like contributors to follow: + * Title your notebook something descriptive. A recommended format is `___.ipynb`; for instance, this might look like `Global_PSL_NMSE_compare_obs_lens.ipynb` or `Greenland_SMB_visual_compare_obs.ipynb`. + * Add a [cell tag](https://jupyterbook.org/en/stable/content/metadata.html#jupyter-cell-tags) `hide-input` for cells which output plots, and add the tag `hide-cell` for cells that do not contain plots (this will hide both the input and output). Do this through JupyterHub when editing your notebook: click `View --> Cell Toolbar --> Tags` and add either `hide-input` or `hide-cell`. This makes it easier to glance at the plots once the webpage is built and not need to scroll through code cells. + * Set up `pre-commit` to ensure that your code is properly formatted and linted. Running `pre-commit install` will configure `git` to automatically run the `pre-commit` checks when you try to commit changes; the commit will only proceed if all the checks pass. diff --git a/docs/conf.py b/docs/conf.py index c427523..7f2aa5a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -18,12 +18,12 @@ print("sys.path:", sys.path) -# Copy README, NCAR_tips, and contributors into docs +# Copy README, NCAR_tips, and contributors, and Contributors_Guide into docs # This block allows us to remove the header image from any md files # without affecting the original version, but still pull the source # into the docs build fresh each time. -for file in ["README.md", "NCAR_tips.md", "contributors.md"]: +for file in ["README.md", "NCAR_tips.md", "contributors.md", "Contributors_Guide.md"]: os.system(f"cp ../{file} ./") # Remove any images from the first line of the file diff --git a/docs/contributors.rst b/docs/contributors_to_cupid.rst similarity index 100% rename from docs/contributors.rst rename to docs/contributors_to_cupid.rst diff --git a/docs/index.rst b/docs/index.rst index b715668..6af8528 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,10 +5,11 @@ CUPiD Documentation :maxdepth: 2 :hidden: + Contributor's Guide Adding Notebooks Configuration File Tips and Tricks for NCAR Machines - Contributors + Contributors .. include:: README.md :parser: myst From 610fc4ef3ab7ecd9cf1ffc9a83e6c5d925d02fb3 Mon Sep 17 00:00:00 2001 From: Teagan King Date: Thu, 17 Oct 2024 09:42:25 -0600 Subject: [PATCH 2/5] update pull request tempalte --- .github/PULL_REQUEST_TEMPLATE.md | 15 +++------------ 1 file changed, 3 insertions(+), 12 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 2a9af34..53469c6 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,16 +1,7 @@ -### All Submissions: +### Description of changes: -* [ ] Have you followed the guidelines in our [Contributor's Guide](https://github.com/NCAR/CUPiD/wiki/Contributor's-Guide) (including the `pre-commit` check)? +* [ ] Have you followed the guidelines in our [Contributor's Guide](https://ncar.github.io/CUPiD/ContributorGuide.html)? * [ ] Have you checked to ensure there aren't other open [Pull Requests](../../../pulls) for the same update/change? - - - -### New Feature Submissions: - -1. [ ] Does your submission pass tests? -2. [ ] Have you lint your code locally prior to submission? - -### Changes to Core Features: - +* [ ] Have you made sure that the `pre-commit` checks passed? * [ ] Have you added an explanation of what your changes do and why you'd like us to include them? * [ ] Have you successfully tested your changes locally? From 4aa0ad26ed89116614941c175f321f434359720c Mon Sep 17 00:00:00 2001 From: Teagan King Date: Thu, 17 Oct 2024 09:58:59 -0600 Subject: [PATCH 3/5] include links --- .github/PULL_REQUEST_TEMPLATE.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 53469c6..549b312 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -2,6 +2,7 @@ * [ ] Have you followed the guidelines in our [Contributor's Guide](https://ncar.github.io/CUPiD/ContributorGuide.html)? * [ ] Have you checked to ensure there aren't other open [Pull Requests](../../../pulls) for the same update/change? -* [ ] Have you made sure that the `pre-commit` checks passed? +* [ ] Have you made sure that the [`pre-commit` checks passed (#8 in Adding Notebooks Guide)](https://ncar.github.io/CUPiD/addingnotebookstocollection.html)? +* [ ] Have you [hidden the code cells (#8 in Adding Notebooks Guide)](https://ncar.github.io/CUPiD/addingnotebookstocollection.html) in your notebook? * [ ] Have you added an explanation of what your changes do and why you'd like us to include them? * [ ] Have you successfully tested your changes locally? From 9f9b15b59202f206794ac14b858e101fa04f9f2e Mon Sep 17 00:00:00 2001 From: Teagan King Date: Mon, 21 Oct 2024 10:47:55 -0600 Subject: [PATCH 4/5] renaming of files, clarification of dev env with precommit --- contributors.md => Contributors.md | 0 NCAR_tips.md => NCARtips.md | 0 README.md | 2 +- docs/{Contributors_Guide.md => ContributorsGuide.md} | 2 +- docs/NCARtips.rst | 2 -- docs/addingnotebookstocollection.md | 4 ++-- docs/conf.py | 4 ++-- docs/{ContributorsGuide.rst => contributors_guide.rst} | 0 docs/contributors_to_cupid.rst | 2 +- docs/index.rst | 4 ++-- docs/ncar_tips.rst | 2 ++ examples/key_metrics/config.yml | 8 ++++---- ...e_PSL.ipynb => Global_PSL_NMSE_compare_obs_lens.ipynb} | 0 ...ostic.ipynb => Greenland_SMB_visual_compare_obs.ipynb} | 0 14 files changed, 15 insertions(+), 15 deletions(-) rename contributors.md => Contributors.md (100%) rename NCAR_tips.md => NCARtips.md (100%) rename docs/{Contributors_Guide.md => ContributorsGuide.md} (95%) delete mode 100644 docs/NCARtips.rst rename docs/{ContributorsGuide.rst => contributors_guide.rst} (100%) create mode 100644 docs/ncar_tips.rst rename examples/nblibrary/atm/{nmse_PSL.ipynb => Global_PSL_NMSE_compare_obs_lens.ipynb} (100%) rename examples/nblibrary/glc/{LIWG_SMB_diagnostic.ipynb => Greenland_SMB_visual_compare_obs.ipynb} (100%) diff --git a/contributors.md b/Contributors.md similarity index 100% rename from contributors.md rename to Contributors.md diff --git a/NCAR_tips.md b/NCARtips.md similarity index 100% rename from NCAR_tips.md rename to NCARtips.md diff --git a/README.md b/README.md index 7832710..f97321a 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ If you do not have `mamba` installed, you can still use `conda`... it will just $ pip install -e . # installs cupid ``` -1. Run `pre-commit install` to configure `git` to automatically run `pre-commit` checks when you try to commit changes; the commit will only proceed if all checks pass. Note that CUPiD uses `pre-commit` to ensure code formatting guidelines are followed, and pull requests will not be accepted if they fail the `pre-commit`-based Github Action. +1. In the `cupid-dev` environment, run `pre-commit install` to configure `git` to automatically run `pre-commit` checks when you try to commit changes from the `cupid-dev` environment; the commit will only proceed if all checks pass. Note that CUPiD uses `pre-commit` to ensure code formatting guidelines are followed, and pull requests will not be accepted if they fail the `pre-commit`-based Github Action. 1. If you plan on contributing code to CUPiD, whether developing CUPiD itself or providing notebooks for CUPiD to run, please see the [Contributor's Guide](https://ncar.github.io/CUPiD/ContributorsGuide.html). diff --git a/docs/Contributors_Guide.md b/docs/ContributorsGuide.md similarity index 95% rename from docs/Contributors_Guide.md rename to docs/ContributorsGuide.md index 9761c34..188f623 100644 --- a/docs/Contributors_Guide.md +++ b/docs/ContributorsGuide.md @@ -11,7 +11,7 @@ In order to contribute code to this repository, we recommend that you get starte 4. [Install CUPiD](https://ncar.github.io/CUPiD/index.html#installing), relevant environments, and setup `pre-commit`. 5. Make your edits and add your name to our `contributors.md` file to make sure we recognize your contributions 6. Merge in recent changes from master -7. Ensure that `pre-commit` checks all pass +7. Ensure that `pre-commit` checks all pass from the `cupid-dev` environment 8. IF updating `github.io` pages, test with the steps listed below, otherwise proceed to #9: - Create the environment necessary for building documentation with `$ conda env create -f environments/docs.yml` - Activate the docs environment: `$ conda activate cupid-docs` diff --git a/docs/NCARtips.rst b/docs/NCARtips.rst deleted file mode 100644 index 8020125..0000000 --- a/docs/NCARtips.rst +++ /dev/null @@ -1,2 +0,0 @@ -.. include:: NCAR_tips.md - :parser: myst diff --git a/docs/addingnotebookstocollection.md b/docs/addingnotebookstocollection.md index c091115..84d01b2 100644 --- a/docs/addingnotebookstocollection.md +++ b/docs/addingnotebookstocollection.md @@ -41,9 +41,9 @@ Generally, a good fit for a diagnostic notebook is one that reads in CESM output 7. Update your parameters. Parameters that are specific to just this notebook should go under `parameter_groups` in the notebook's entry under `compute_notebooks`. Global parameters that you want passed in to every notebook in the collection should go under `global_params`. When `CUPiD` executes your notebook, all of these parameters will get put in a new cell below the cell tagged `parameters` that you added in step 3. This means they will supercede the values of the parameters that you put in the cell above---the names, notation, etc. should match to make sure your notebook is able to find the variables it needs. -8. Your collection can now be run and built with `cupid-run` and `cupid-build` as usual. +8. Your collection can now be run with `cupid-run`, and then the website can be built with `cupid-build`. 9. If you're happy with your notebook and want to add it to the CUPiD repository, there are a few formatting items that we would like contributors to follow: * Title your notebook something descriptive. A recommended format is `___.ipynb`; for instance, this might look like `Global_PSL_NMSE_compare_obs_lens.ipynb` or `Greenland_SMB_visual_compare_obs.ipynb`. * Add a [cell tag](https://jupyterbook.org/en/stable/content/metadata.html#jupyter-cell-tags) `hide-input` for cells which output plots, and add the tag `hide-cell` for cells that do not contain plots (this will hide both the input and output). Do this through JupyterHub when editing your notebook: click `View --> Cell Toolbar --> Tags` and add either `hide-input` or `hide-cell`. This makes it easier to glance at the plots once the webpage is built and not need to scroll through code cells. - * Set up `pre-commit` to ensure that your code is properly formatted and linted. Running `pre-commit install` will configure `git` to automatically run the `pre-commit` checks when you try to commit changes; the commit will only proceed if all the checks pass. + * Set up `pre-commit` in the `cupid-dev` environment to ensure that your code is properly formatted and linted. Running `pre-commit install` will configure `git` to automatically run the `pre-commit` checks when you try to commit changes; the commit will only proceed if all the checks pass. diff --git a/docs/conf.py b/docs/conf.py index 7f2aa5a..b1585b3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -18,12 +18,12 @@ print("sys.path:", sys.path) -# Copy README, NCAR_tips, and contributors, and Contributors_Guide into docs +# Copy README, NCAR_tips, and Contributors into docs # This block allows us to remove the header image from any md files # without affecting the original version, but still pull the source # into the docs build fresh each time. -for file in ["README.md", "NCAR_tips.md", "contributors.md", "Contributors_Guide.md"]: +for file in ["README.md", "NCARtips.md", "Contributors.md"]: os.system(f"cp ../{file} ./") # Remove any images from the first line of the file diff --git a/docs/ContributorsGuide.rst b/docs/contributors_guide.rst similarity index 100% rename from docs/ContributorsGuide.rst rename to docs/contributors_guide.rst diff --git a/docs/contributors_to_cupid.rst b/docs/contributors_to_cupid.rst index 7274658..387d893 100644 --- a/docs/contributors_to_cupid.rst +++ b/docs/contributors_to_cupid.rst @@ -1,2 +1,2 @@ -.. include:: contributors.md +.. include:: Contributors.md :parser: myst diff --git a/docs/index.rst b/docs/index.rst index 6af8528..e636b49 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,10 +5,10 @@ CUPiD Documentation :maxdepth: 2 :hidden: - Contributor's Guide + Contributor's Guide Adding Notebooks Configuration File - Tips and Tricks for NCAR Machines + Tips and Tricks for NCAR Machines Contributors .. include:: README.md diff --git a/docs/ncar_tips.rst b/docs/ncar_tips.rst new file mode 100644 index 0000000..3bd2869 --- /dev/null +++ b/docs/ncar_tips.rst @@ -0,0 +1,2 @@ +.. include:: NCARtips.md + :parser: myst diff --git a/examples/key_metrics/config.yml b/examples/key_metrics/config.yml index e559ee7..17a0b9e 100644 --- a/examples/key_metrics/config.yml +++ b/examples/key_metrics/config.yml @@ -114,7 +114,7 @@ compute_notebooks: none: {} atm: - nmse_PSL: + Global_PSL_NMSE_compare_obs_lens: parameter_groups: none: regridded_output: False # it looks like output is already on f09 grid, didn't need to regrid time-series file @@ -122,7 +122,7 @@ compute_notebooks: validation_path: '/glade/campaign/cesm/development/cross-wg/diagnostic_framework/nmse_validation/fv0.9x1.25' glc: - LIWG_SMB_diagnostic: + Greenland_SMB_visual_compare_obs: parameter_groups: none: obs_path: '/glade/u/home/gunterl/obs_diagnostic_cesm/' @@ -191,7 +191,7 @@ book_toc: - caption: Atmosphere chapters: - - file: atm/nmse_PSL + - file: atm/Global_PSL_NMSE_compare_obs_lens # - caption: Ocean # chapters: @@ -207,7 +207,7 @@ book_toc: - caption: Land Ice chapters: - - file: glc/LIWG_SMB_diagnostic + - file: glc/Greenland_SMB_visual_compare_obs ##################################### # Keys for Jupyter Book _config.yml # diff --git a/examples/nblibrary/atm/nmse_PSL.ipynb b/examples/nblibrary/atm/Global_PSL_NMSE_compare_obs_lens.ipynb similarity index 100% rename from examples/nblibrary/atm/nmse_PSL.ipynb rename to examples/nblibrary/atm/Global_PSL_NMSE_compare_obs_lens.ipynb diff --git a/examples/nblibrary/glc/LIWG_SMB_diagnostic.ipynb b/examples/nblibrary/glc/Greenland_SMB_visual_compare_obs.ipynb similarity index 100% rename from examples/nblibrary/glc/LIWG_SMB_diagnostic.ipynb rename to examples/nblibrary/glc/Greenland_SMB_visual_compare_obs.ipynb From 53b5057e075c652d28c6ff88fcb51bc9205a450c Mon Sep 17 00:00:00 2001 From: Teagan King Date: Mon, 21 Oct 2024 11:02:11 -0600 Subject: [PATCH 5/5] update links --- README.md | 2 +- docs/addingnotebookstocollection.md | 2 +- docs/contributors_guide.rst | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index f97321a..cb226a3 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ If you do not have `mamba` installed, you can still use `conda`... it will just 1. In the `cupid-dev` environment, run `pre-commit install` to configure `git` to automatically run `pre-commit` checks when you try to commit changes from the `cupid-dev` environment; the commit will only proceed if all checks pass. Note that CUPiD uses `pre-commit` to ensure code formatting guidelines are followed, and pull requests will not be accepted if they fail the `pre-commit`-based Github Action. 1. If you plan on contributing code to CUPiD, whether developing CUPiD itself or providing notebooks for CUPiD to run, -please see the [Contributor's Guide](https://ncar.github.io/CUPiD/ContributorsGuide.html). +please see the [Contributor's Guide](https://ncar.github.io/CUPiD/contributors_guide.html). ## Running diff --git a/docs/addingnotebookstocollection.md b/docs/addingnotebookstocollection.md index 84d01b2..9ef0a4b 100644 --- a/docs/addingnotebookstocollection.md +++ b/docs/addingnotebookstocollection.md @@ -2,7 +2,7 @@ Generally, a good fit for a diagnostic notebook is one that reads in CESM output, does some processing, and outputs plots, values, and/or new files (images, data, etc.) that are useful for evaluating the run. -0. Check out our [Contributor's Guide](https://ncar.github.io/CUPiD/ContributorsGuide.html) to make ensure appropriate setup of your git repository for contributions. +0. Check out our [Contributor's Guide](https://ncar.github.io/CUPiD/contributors_guide.html) to make ensure appropriate setup of your git repository for contributions. 1. Install the `environments/cupid-analysis.yml` environment (see [installation instructions](https://ncar.github.io/CUPiD/index.html#installing)). Make sure that your notebook runs properly in this environment. If there are conflicts or missing dependencies, open an issue or talk to CUPiD developers so we can find a solution. 2. In your notebook, move all variables you might want to change (paths to data, dates to select, etc.) to a cell near the top. For example: diff --git a/docs/contributors_guide.rst b/docs/contributors_guide.rst index 69c2120..219d1ad 100644 --- a/docs/contributors_guide.rst +++ b/docs/contributors_guide.rst @@ -1,2 +1,2 @@ -.. include:: Contributors_Guide.md +.. include:: ContributorsGuide.md :parser: myst