diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index ea8d62327..9a9d8f913 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,15 +1,22 @@ - + + +Closes #XXX -Closes #XXX + or "Fixes part of #YYY but does not fully close it." --> ## Overview - + + + + + ## Expected Usage + **General** - [ ] An issue is created and linked @@ -38,29 +45,18 @@ other_output = uxds.some_function(some_param = True) - [ ] Filled out Overview and Expected Usage (if applicable) sections **Testing & Benchmarking** - -- [ ] Adequate tests are created if there is new functionality -- [ ] Tests are not too basic (such as simply calling a function and nothing else) -- [ ] Tests cover all major paths in your new functions +- [ ] There is adequate test coverage of changes from this PR (add new tests if needed) - [ ] If this PR could affect performance, ran ASV benchmarks and confirmed they show expected behavior (add a new benchmark if necessary) -**Documentation** - -- [ ] Docstrings have been added to all new functions -- [ ] Docstrings have been updated with any function changes -- [ ] User (public) functions have been added to `docs/api.rst` -- [ ] Internal (private) function names start with an underscore (`_`) - -**Examples** - -- [ ] **All** notebook examples cleared the output of all cells before committing -- [ ] New notebook examples added to appropriate folder (gallery: `docs/examples/`; guide: `docs/user-guide/`; quickstart: `docs/getting-started/`) -- [ ] New notebook examples referenced in appropriate .rst file (gallery: `docs/gallery.rst`; guide: `docs/userguide.rst`; quickstart: `docs/quickstart.rst`) -- [ ] New notebook gallery examples added entry in `docs/gallery.yml` with appropriate thumbnail photo in `docs/_static/thumbnails/` - +**Documentation and Examples** +- [ ] Docstrings updated with any function changes, and included in all new functions +- [ ] User (public) functions added to `docs/api.rst`; internal (private) function names start with an underscore (`_`) +- [ ] If touched any notebook files, cleared the output of all cells before committing +- [ ] If added new notebook files, put into appropriate directories and referenced in appropriate files + ## AI Disclosure diff --git a/docs/contributing.rst b/docs/contributing.rst index 3e2570cbc..cffde8e8f 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -623,10 +623,23 @@ file so that its documentation page is automatically generated. needed. However, it would be a great practice to provide usage examples in the same PR, especially for demonstrating the use of complex UXarray functions. -The UXarray documentation houses ``docs/examples/.ipynb`` files (paths -relative from the root directory) to provide `Usage Examples `_ to be -automatically generated. If you prefer to provide usage examples for the work you -have put together, please be sure to put your notebook(s) under this same directory. +The UXarray documentation pages are built from a combination of ``.rst`` and ``.ipynb`` files. +Jupyter notebook files should be cleared of all outputs before committing, and will be run and +linked in the docs automatically when when the docs pages are built, as long as there is +at least one reference to them in the appropriate ``.rst`` file(s). + +To add a usage example to the `Gallery `_, be sure to +put the notebook file into the ``docs/examples/`` directory, +add a reference to it in both the ``docs/gallery.rst`` and ``docs/gallery.yml`` files, +and add a thumbnail photo into ``docs/_static/thumbnails/``. + +To add a page to the `User Guide `_, be sure to +put the notebook file into the ``docs/user-guide/`` directory, +and add a reference to it in the ``docs/userguide.rst`` file. + +To add a page to the `Getting Started / Quick Start Guide `_, be sure to +put the notebook file into the ``docs/getting-started/`` directory, +and add a reference to it in the ``docs/quickstart.rst`` file. 3.7.4. After You Open The Pull Request ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^