Merge remote-tracking branch 'upstream/master' into dzu-dzt

* upstream/master:
  📚 New docs theme & Add comments (NCAR#74)

CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## v2021.xx.xx (unreleased)
+
+### Bug Fixes
+
+### Breaking Changes
+
+### Internal Changes
+
+### Documentation
+
+### Contributors to this release
+
+## v2020.12.15
+
+([full changelog](https://github.com/NCAR/pop-tools/compare/4aba19d40d5aec44b6032b5031f655ed3c40040e...bd1236ca615b32595c43cfa689e85fc9a112eb9f))
+
+### Internal Changes
+
+- ⬆️ Upgrade dependencies and pin minimum versions [#68](https://github.com/NCAR/pop-tools/pull/68) ([@andersy005](https://github.com/andersy005))
+
+- 💚 Migrate CI from CircleCI to GHA [#67](https://github.com/NCAR/pop-tools/pull/67) ([@andersy005](https://github.com/andersy005))
+- Use vectorize instead of jit in EOS [#66](https://github.com/NCAR/pop-tools/pull/66) ([@rabernat](https://github.com/rabernat))
+- Update pooch downloader: use `CESMDATAROOT` variable when available [#52](https://github.com/NCAR/pop-tools/pull/52) ([@andersy005](https://github.com/andersy005))
+
+### Contributors to this release
+
+([GitHub contributors page for this release](https://github.com/NCAR/pop-tools/graphs/contributors?from=2020-09-14&to=2020-12-16&type=c))
+
+[@andersy005](https://github.com/search?q=repo%3ANCAR%2Fpop-tools+involves%3Aandersy005+updated%3A2020-09-14..2020-12-16&type=Issues) | [@klindsay28](https://github.com/search?q=repo%3ANCAR%2Fpop-tools+involves%3Aklindsay28+updated%3A2020-09-14..2020-12-16&type=Issues) | [@kmpaul](https://github.com/search?q=repo%3ANCAR%2Fpop-tools+involves%3Akmpaul+updated%3A2020-09-14..2020-12-16&type=Issues) | [@matt-long](https://github.com/search?q=repo%3ANCAR%2Fpop-tools+involves%3Amatt-long+updated%3A2020-09-14..2020-12-16&type=Issues) | [@rabernat](https://github.com/search?q=repo%3ANCAR%2Fpop-tools+involves%3Arabernat+updated%3A2020-09-14..2020-12-16&type=Issues)

CONTRIBUTING.md

@@ -0,0 +1,144 @@
+# Contributing Guide
+
+- [Contributing Guide](#contributing-guide)
+  - [Feature requests and feedback](#feature-requests-and-feedback)
+  - [Report bugs](#report-bugs)
+  - [Fix bugs](#fix-bugs)
+  - [Write documentation](#write-documentation)
+  - [Preparing Pull Requests](#preparing-pull-requests)
+
+Interested in helping build pop-tools? Have code from your work that
+you believe others will find useful? Have a few minutes to tackle an issue?
+
+Contributions are highly welcomed and appreciated. Every little help counts,
+so do not hesitate!
+
+The following sections cover some general guidelines
+regarding development in pop-tools for maintainers and contributors.
+Nothing here is set in stone and can't be changed.
+Feel free to suggest improvements or changes in the workflow.
+
+## Feature requests and feedback
+
+We'd also like to hear about your propositions and suggestions. Feel free to
+submit them as issues on [pop-tools's GitHub issue tracker](https://github.com/NCAR/pop-tools) and:
+
+- Explain in detail how they should work.
+- Keep the scope as narrow as possible. This will make it easier to implement.
+
+## Report bugs
+
+Report bugs for pop-tools in the [issue tracker](https://github.com/NCAR/pop-tools).
+
+If you are reporting a bug, please include:
+
+- Your operating system name and version.
+- Any details about your local setup that might be helpful in troubleshooting,
+  specifically the Python interpreter version, installed libraries, and pop-tools
+  version.
+- Detailed steps to reproduce the bug.
+
+If you can write a demonstration test that currently fails but should pass
+(xfail), that is a very useful commit to make as well, even if you cannot
+fix the bug itself.
+
+## Fix bugs
+
+Look through the [GitHub issues for bugs](https://github.com/NCAR/pop-tools/labels/type:%20bug).
+
+Talk to developers to find out how you can fix specific bugs.
+
+## Write documentation
+
+pop-tools could always use more documentation. What exactly is needed?
+
+- More complementary documentation. Have you perhaps found something unclear?
+- Docstrings. There can never be too many of them.
+- Blog posts, articles and such -- they're all very appreciated.
+
+You can also edit documentation files directly in the GitHub web interface,
+without using a local copy. This can be convenient for small fixes.
+
+Build the documentation locally with the following command:
+
+```bash
+$ make docs
+```
+
+## Preparing Pull Requests
+
+1. Fork the [pop-tools GitHub repository](https://github.com/NCAR/pop-tools).
+
+2. Clone your fork locally using [git](https://git-scm.com/), connect your repository
+   to the upstream (main project), and create a branch::
+
+   ```bash
+   $ git clone [email protected]:YOUR_GITHUB_USERNAME/pop-tools.git
+   $ cd pop-tools
+   $ git remote add upstream [email protected]:NCAR/pop-tools.git
+   ```
+
+   now, to fix a bug or add feature create your own branch off "master":
+
+   ```bash
+   $ git checkout -b your-bugfix-feature-branch-name master
+   ```
+
+   If you need some help with Git, follow this quick start
+   guide: https://git.wiki.kernel.org/index.php/QuickStart
+
+3. Install dependencies into a new conda environment::
+
+   ```bash
+   $ conda env update -f ci/environment.yml
+   $ conda activate pop-tools-dev
+   ```
+
+4. Make an editable install of pop-tools by running::
+
+   ```bash
+   $ python -m pip install -e .
+   ```
+
+5. Install [pre-commit](https://pre-commit.com) hooks on the pop-tools repo::
+
+   ```bash
+   $ pre-commit install
+   ```
+
+   Afterwards `pre-commit` will run whenever you commit.
+
+   [pre-commit](https://pre-commit.com) is a framework for managing and maintaining multi-language pre-commit hooks to ensure code-style and code formatting is consistent.
+
+   Now you have an environment called `pop-tools-dev` that you can work in.
+   You’ll need to make sure to activate that environment next time you want
+   to use it after closing the terminal or your system.
+
+6. (Optional) Run all the tests
+
+   Now running tests is as simple as issuing this command::
+
+   ```bash
+   $ pytest --cov=./
+   ```
+
+   This command will run tests via the `pytest` tool.
+
+7. Commit and push once your tests pass and you are happy with your change(s)::
+
+   When committing, `pre-commit` will re-format the files if necessary.
+
+   ```bash
+   $ git commit -a -m "<commit message>"
+   $ git push -u
+   ```
+
+8. Finally, submit a pull request through the GitHub website using this data::
+
+   ```console
+   head-fork: YOUR_GITHUB_USERNAME/pop-tools
+   compare: your-branch-name
+
+   base-fork: NCAR/pop-tools
+   base: master # if it's a bugfix or feature
+   ```

MANIFEST.in

@@ -3,7 +3,7 @@ recursive-include pop_tools *.yaml
 recursive-include pop_tools *.txt
 include pop_tools/input_templates/*
 include LICENSE
-include README.rst
+include README.md
 include requirements.txt
 
 recursive-exclude * __pycache__

README.md

@@ -0,0 +1,38 @@
+# POP-tools: Tools to support analysis of POP2-CESM model solutions with xarray
+
+| CI          | [![GitHub Workflow Status][github-ci-badge]][github-ci-link] [![GitHub Workflow Status][github-lint-badge]][github-lint-link] [![Code Coverage Status][codecov-badge]][codecov-link] |
+| :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
+| **Docs**    |                                                                    [![Documentation Status][rtd-badge]][rtd-link]                                                                    |
+| **Package** |                                                         [![Conda][conda-badge]][conda-link] [![PyPI][pypi-badge]][pypi-link]                                                         |
+| **License** |                                                                        [![License][license-badge]][repo-link]                                                                        |
+
+## Installation
+
+pop-tools can be installed from PyPI with pip:
+
+```bash
+python -m pip install pop-tools
+```
+
+pop-tools is also available from conda-forge for conda installations:
+
+```bash
+conda install -c conda-forge pop-tools
+```
+
+See [documentation](https://pop-tools.readthedocs.io) for more information.
+
+[github-ci-badge]: https://img.shields.io/github/workflow/status/NCAR/pop-tools/CI?label=CI&logo=github&style=for-the-badge
+[github-lint-badge]: https://img.shields.io/github/workflow/status/NCAR/pop-tools/linting?label=linting&logo=github&style=for-the-badge
+[github-ci-link]: https://github.com/NCAR/pop-tools/actions?query=workflow%3ACI
+[github-lint-link]: https://github.com/NCAR/pop-tools/actions?query=workflow%3Alinting
+[codecov-badge]: https://img.shields.io/codecov/c/github/NCAR/pop-tools.svg?logo=codecov&style=for-the-badge
+[codecov-link]: https://codecov.io/gh/NCAR/pop-tools
+[rtd-badge]: https://img.shields.io/readthedocs/pop-tools/latest.svg?style=for-the-badge
+[rtd-link]: https://pop-tools.readthedocs.io/en/latest/?badge=latest
+[pypi-badge]: https://img.shields.io/pypi/v/pop-tools?logo=pypi&style=for-the-badge
+[pypi-link]: https://pypi.org/project/pop-tools
+[conda-badge]: https://img.shields.io/conda/vn/conda-forge/pop-tools?logo=anaconda&style=for-the-badge
+[conda-link]: https://anaconda.org/conda-forge/pop-tools
+[license-badge]: https://img.shields.io/github/license/NCAR/pop-tools?style=for-the-badge
+[repo-link]: https://github.com/NCAR/pop-tools

docs/_static/css/style.css

@@ -0,0 +1,15 @@
+/* Reduce left and right margins */
+
+.container,
+.container-lg,
+.container-md,
+.container-sm,
+.container-xl {
+  max-width: 1600px !important;
+}
+
+/* Make sidebar sticky */
+
+.bd-sidebar {
+  position: sticky !important;
+}

docs/environment.yml

@@ -0,0 +1,26 @@
+name: pop-tools-docs
+channels:
+  - conda-forge
+  - nodefaults
+dependencies:
+  - dask
+  - fsspec
+  - jupyterlab
+  - matplotlib
+  - myst-nb
+  - netcdf4
+  - numba
+  - pip
+  - pooch
+  - python=3.8
+  - sphinx-book-theme >= 0.0.38
+  - sphinx-copybutton
+  - watermark
+  - xarray
+  - xgcm
+  - zarr
+  - pip:
+      - sphinxext-opengraph
+      - sphinx-comments
+      - -r ../requirements.txt
+      - -e ..

docs/source/changelog.md

@@ -0,0 +1,3 @@
+```{include} ../../CHANGELOG.md
+
+```