Merge pull request #147 from TeaganKing/docs

Documentation updates: contributor's guide, notebook name standardization, hiding code cells
NCAR · Oct 21, 2024 · 942228e · 942228e
2 parents 92b0c30 + 53b5057
commit 942228e
Show file tree

Hide file tree

Showing 16 changed files with 52 additions and 28 deletions.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,16 +1,8 @@
-### 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?
-
-<!-- You can erase any parts of this template not applicable to your Pull Request. -->
-
-### 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 (#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?
diff --git a/contributors.md → Contributors.md b/contributors.md → Contributors.md
diff --git a/NCAR_tips.md → NCARtips.md b/NCAR_tips.md → NCARtips.md
diff --git a/README.md b/README.md
@@ -45,11 +45,10 @@ If you do not have `mamba` installed, you can still use `conda`... it will just
    $ pip install -e .  # installs cupid
    ```
 
+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 [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/contributors_guide.html).
 
 ## Running
 

diff --git a/docs/ContributorsGuide.md b/docs/ContributorsGuide.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/<YOUR GIT USERNAME>/CUPiD`
+3. Check out a new branch with a name that is relevant to the changes you want to make: `git checkout -b <BRANCH NAME>`
+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 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`
+    - 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/NCARtips.rst b/docs/NCARtips.rst
diff --git 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/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:
 
@@ -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 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 `<region>_<variable>_<metric>_<comparisons>.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` 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
@@ -18,12 +18,12 @@
 
 print("sys.path:", sys.path)
 
-# Copy README, NCAR_tips, and contributors 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"]:
+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/contributors.rst b/docs/contributors.rst
diff --git a/docs/contributors_guide.rst b/docs/contributors_guide.rst
@@ -0,0 +1,2 @@
+.. include:: ContributorsGuide.md
+   :parser: myst
diff --git a/docs/contributors_to_cupid.rst b/docs/contributors_to_cupid.rst
@@ -0,0 +1,2 @@
+.. include:: Contributors.md
+   :parser: myst
diff --git a/docs/index.rst b/docs/index.rst
@@ -5,10 +5,11 @@ CUPiD Documentation
    :maxdepth: 2
    :hidden:
 
+    Contributor's Guide <contributors_guide.rst>
     Adding Notebooks <addingnotebookstocollection.md>
     Configuration File <config.md>
-    Tips and Tricks for NCAR Machines <NCARtips.rst>
-    Contributors <contributors.rst>
+    Tips and Tricks for NCAR Machines <ncar_tips.rst>
+    Contributors <contributors_to_cupid.rst>
 
 .. include:: README.md
    :parser: myst
diff --git a/docs/ncar_tips.rst 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
@@ -114,15 +114,15 @@ 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
             base_regridded_output: True
             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 → ...tm/Global_PSL_NMSE_compare_obs_lens.ipynb b/examples/nblibrary/atm/nmse_PSL.ipynb → ...tm/Global_PSL_NMSE_compare_obs_lens.ipynb
diff --git a/...s/nblibrary/glc/LIWG_SMB_diagnostic.ipynb → ...lc/Greenland_SMB_visual_compare_obs.ipynb b/...s/nblibrary/glc/LIWG_SMB_diagnostic.ipynb → ...lc/Greenland_SMB_visual_compare_obs.ipynb