diff --git a/.gitignore b/.gitignore index f2b99889..8b6882f0 100644 --- a/.gitignore +++ b/.gitignore @@ -117,7 +117,5 @@ conda-build/ # Ad-hoc QA qa/ -# Sphinx generated .txt files -notebook-examples.txt -team-panel.txt -demos.txt \ No newline at end of file +# Custom Sphinx generated .txt files. +docs/*.txt diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 1d79514d..3605d505 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,394 +1,360 @@ .. highlight:: shell -============ -Contributing -============ - -Contributions are welcome and greatly appreciated! Every little bit helps, and credit will always be given. - -Types of Contributions ----------------------- - -xCDAT includes issue templates based on the contribution type: https://github.com/xCDAT/xcdat/issues/new/choose. -Note, new contributions must be made under the Apache-2.0 with LLVM exception license. - -Bug Report -~~~~~~~~~~ - -Look through the `GitHub Issues`_ for bugs to fix. Any unassigned issues tagged with "Type: Bug" is open for implementation. - -Feature Request -~~~~~~~~~~~~~~~ - -Look through the `GitHub Issues`_ for feature suggestions. Any unassigned issues tagged with "Type: Enhancement" is open for implementation. - -If you are proposing a feature: - -* Explain in detail how it would work. -* Keep the scope as narrow as possible, to make it easier to implement. -* Remember that this is a open-source project, and that contributions are welcome :) - -Features must meet the following criteria before they are considered for implementation: - -1. Feature is not implemented by ``xarray`` -2. Feature is not implemented in another actively developed xarray-based package - - * For example, `cf_xarray`_ already handles interpretation of `CF convention`_ attributes on xarray objects - -3. Feature is not limited to specific use cases (e.g., data quality issues) -4. Feature is generally reusable -5. Feature is relatively simple and lightweight to implement and use +.. note:: -Documentation Update -~~~~~~~~~~~~~~~~~~~~ + Large portions of this document came from or are inspired by the `Xarray Contributing + Guide `_. -Help improve xCDAT's documentation, whether that be the Sphinx documentation or the API docstrings. +============ +Overview +============ -Community Discussion -~~~~~~~~~~~~~~~~~~~~ +xCDAT is a community-driven open source project and we welcome everyone who would like to +contribute! Feel free to open a `GitHub Issue`_ for bug reports, bug fixes, +documentation improvements, enhancement suggestions, and other ideas. -Take a look at the `GitHub Discussions`_ page to get involved, share ideas, or ask questions. +We encourage discussion on any xCDAT related topic in the `GitHub Discussion`_ forum. +You can also subscribe to our `mailing list`_ for news and announcements related to xCDAT, +such as software version releases or future roadmap plans. -.. _cf_xarray: https://cf-xarray.readthedocs.io/en/latest/index.html -.. _CF convention: http://cfconventions.org/ -.. _GitHub Issues: https://github.com/xCDAT/xcdat/issues -.. _GitHub Discussions: https://github.com/xCDAT/xcdat/discussions +Please note that xCDAT has a `Code of Conduct`_. By participating in the xCDAT +community, you agree to abide by its rules. -Version Control +Where to start? --------------- -The repository uses branch-based (core team) and fork-based (external collaborators) -Git workflows with tagged software releases. +If you are brand new to xCDAT or open-source development, we recommend going +through the `GitHub Issues`_ page to find issues that interest you. If you are +interested in opening a GitHub Issue, you can use these `templates`_. -.. figure:: _static/git-flow.svg - :alt: Git Flow Diagram +Some issues are particularly suited for new contributors by the label +`type: docs `_ and +`good-first-issue `_ where +you could start out. These are well documented issues, that do not require a deep +understanding of the internals of xCDAT. Once you've found an interesting issue, you can +return here to get your development environment setup. -Guidelines -~~~~~~~~~~ +**New contributions must be made under the Apache-2.0 with LLVM exception license.** -1. ``main`` must always be deployable -2. All changes are made through support branches -3. Rebase with the latest ``main`` to avoid/resolve conflicts -4. Make sure pre-commit quality assurance checks pass when committing (enforced in CI/CD build) -5. Open a pull request early for discussion -6. Once the CI/CD build passes and pull request is approved, squash and rebase your commits -7. Merge pull request into ``main`` and delete the branch +Documentation updates +~~~~~~~~~~~~~~~~~~~~~ -Things to Avoid -~~~~~~~~~~~~~~~ - -1. Don't merge in broken or commented out code -2. Don't commit directly to ``main`` +Contributing to the `documentation`_ is an excellent way to help xCDAT. Anything from +fixing typos to improving sentence structure or API docstrings/examples can go a long +way in making xCDAT more user-friendly. - * There are branch-protection rules for ``main`` +To open a documentation update request, please use the `documentation update template`_. -3. Don't merge with conflicts. Instead, handle conflicts upon rebasing +Bug reports +~~~~~~~~~~~ +Bug reports are an important part of making xCDAT more stable. Having a complete bug +report will allow others to reproduce the bug and provide insight into fixing. -Source: https://gist.github.com/jbenet/ee6c9ac48068889b0912 +Trying out the bug-producing code on the ``main`` branch is often a worthwhile exercise +to confirm that the bug still exists. It is also worth searching existing bug reports and +pull requests to see if the issue has already been reported and/or fixed. -Pre-commit -~~~~~~~~~~ -The repository uses the pre-commit package to manage pre-commit hooks. -These hooks help with quality assurance standards by identifying simple issues -at the commit level before submitting code reviews. +To open a new bug report, please use this issue `bug report template`_. -.. figure:: _static/pre-commit-flow.svg - :alt: Pre-commit Flow Diagram +Enhancement requests +~~~~~~~~~~~~~~~~~~~~ +Enhancements are a great way to improve xCDAT's capabilities for the broader scientific +community. - pre-commit Flow +If you are proposing an enhancement: +* Explain in detail how it would work +* Make sure it fits in the domain of geospatial climate science +* Keep the scope as narrow as possible, to make it easier to implement +* Generally reusable among the community (not model or data-specific) +* Remember that this is a open-source project, and that contributions are welcome :) -Get Started ------------- +To open a new enhancement request, please use this issue `enhancement request template`_. -Ready to contribute? Here's how to set up xCDAT for local development. +All other inquiries +~~~~~~~~~~~~~~~~~~~~ -VS Code, the editor of choice -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +We welcome comments, questions, or feedback! Please share your thoughts on the +`GitHub Discussions`_ forum! -We recommend using VS Code as your IDE because it is open-source and has great Python development support. +Version control, Git, and GitHub +-------------------------------- -Get VS Code here: https://code.visualstudio.com +The code is hosted on `GitHub`_. To contribute you will need to sign up for a +`free GitHub account`_. We use `Git`_ for version control to allow many people to work +together on the project. -VS Code Setup -^^^^^^^^^^^^^ -xCDAT includes a VS Code workspace file (``.vscode/xcdat.code-setting``). This file automatically configures your IDE with the quality assurance tools, code line-length rulers, and more. +Some great resources for learning Git: -Make sure to follow the :ref:`Local Development` section below. +* the `GitHub help pages`_ +* the `NumPy's documentation`_ +* Matthew Brett's `Pydagogue`_ -Recommended VS Code Extensions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - * `Python `_ - * `Pylance `_ - * `Python Docstring Generator `_ - * `Python Type Hint `_ - * `Better Comments `_ - * `Jupyter `_ - * `Visual Studio Intellicode `_ - - -.. _Local Development: +Getting started with Git +~~~~~~~~~~~~~~~~~~~~~~~~ -Local Development -~~~~~~~~~~~~~~~~~ +`GitHub has instructions for setting up Git`_ including installing git, +setting up your SSH key, and configuring git. All these steps need to be completed before +you can work seamlessly between your local repository and GitHub. -1. Download and install Conda +Set up the Repo +~~~~~~~~~~~~~~~ - Linux - :: +.. note:: - $ wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh - $ bash ./Miniconda3-latest-Linux-x86_64.sh - Do you wish the installer to initialize Miniconda3 by running conda init? [yes|no] yes + The following instructions assume you want to learn how to interact with GitHub via + the git command-line utility, but contributors who are new to git may find it easier + to use other tools instead such as `GitHub Desktop`_. +Once you have Git setup, you have two options for working with the ``xcdat`` repository: +(1) Clone the main repository, (2) Fork the main repository and clone your fork. - MacOS - :: +1. Clone the main repository - $ wget https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh - $ bash ./Miniconda3-latest-MacOSX-x86_64.sh - Do you wish the installer to initialize Miniconda3 by running conda init? [yes|no] yes + - If you are a regular xCDAT contributor and have direct write access to the main repository, you can + clone the main repository running ``git clone https://github.com/xCDAT/xcdat.git``. -2. Fork the ``xcdat`` repo on GitHub. +2. Fork the main repository and clone your fork - - If you are a maintainer, you can clone and branch directly from the root repository here: https://github.com/xCDAT/xcdat + - If you are not a regular xCDAT contributor and don't have write access to the main + repository, you will need to fork the main repository then clone your fork. + - Head over to the `GitHub`_ repository page, click the fork button, and click + "Create a new fork" (shown below). + - .. image:: _static/github-fork-button.png + - Then clone your fork by running ``git clone https://github.com//xcdat.git`` -3. Clone your fork locally:: +.. _GitHub has instructions for setting up Git: https://help.github.com/set-up-git-redirect +.. _templates: https://github.com/xCDAT/xcdat/issues/new/choose +.. _documentation: https://xcdat.readthedocs.io/en/latest/ +.. _GitHub Issues: https://github.com/xCDAT/xcdat/issues +.. _documentation update template: https://github.com/xCDAT/xcdat/issues/new?assignees=&labels=Type%3A+Documentation&projects=&template=documentation.yml&title=%5BDoc%5D%3A+ +.. _bug report template: https://github.com/xCDAT/xcdat/issues/new?assignees=&labels=Type%3A+Bug&projects=&template=bug_report.yml&title=%5BBug%5D%3A+ +.. _enhancement request template: https://github.com/xCDAT/xcdat/issues/new?assignees=&labels=Type%3A+Enhancement&projects=&template=feature_request.yml&title=%5BFeature%5D%3A+ +.. _GitHub Issue: https://github.com/xCDAT/xcdat/issues +.. _GitHub Issues: https://github.com/xCDAT/xcdat/issues +.. _GitHub Discussion: https://github.com/xCDAT/xcdat/discussions +.. _GitHub Discussions: https://github.com/xCDAT/xcdat/discussions +.. _Code of Conduct: CODE-OF-CONDUCT.rst +.. _mailing list: https://groups.google.com/g/xcdat +.. _GitHub: https://www.github.com/xCDAT/xcdat +.. _free GitHub account: https://github.com/signup/free +.. _Git: http://git-scm.com/ +.. _GitHub help pages: https://help.github.com/ +.. _NumPy's documentation: https://numpy.org/doc/stable/dev/index.html +.. _Pydagogue: https://matthew-brett.github.io/pydagogue/ +.. _GitHub Desktop: https://desktop.github.com/ - $ git clone git@github.com:your_name_here/xcdat.git +Creating a development environment +---------------------------------- -4. Open ``.vscode/xcdat.code-settings`` in VS Code +Before starting any development, you'll need to create an isolated xCDAT +development environment: +- We recommend installing `Anaconda`_ or `Miniconda`_ +- Make sure your conda is up to date (``conda update conda``) +- Make sure that you have forked and cloned the `repository`_. If you are in the xCDAT + organization, forking is not needed since you will have direct read access to the repository +- ``cd`` to the ``xcdat`` source directory -5. Create and activate Conda development environment:: +Now we are going through a two-step process. This will create the new environment, and +not touch any of your existing environments, nor any existing Python installation. - $ cd xcdat - $ conda env create -f conda-env/dev.yml - $ conda activate xcdat_dev +1. Install the build dependencies and install the local build of ``xcdat``. -6. Set VS Code Python interpretor to ``xcdat_dev`` + .. code-block:: bash -7. Install pre-commit:: + >>> conda env create -f conda-env/dev.yml + >>> conda activate xcdat_dev + >>> + >>> make install # or python -m pip install . - $ pre-commit install - pre-commit installed at .git/hooks/pre-commit +2. At this point you should be able to import ``xcdat`` from your locally built version: -8. Create a branch for local development and make changes:: + .. code-block:: bash - $ git checkout -b + $ python # start an interpreter + >>> import xcdat + >>> xcdat.__version__ + '0.6.1' -9. `` During or after making changes, check for formatting or linting issues using pre-commit:: - # Step 9 performs this automatically on staged files in a commit - $ pre-commit run --all-files +To view your environments: - Trim Trailing Whitespace.................................................Passed - Fix End of Files.........................................................Passed - Check Yaml...............................................................Passed - black....................................................................Passed - isort....................................................................Passed - flake8...................................................................Passed - mypy.....................................................................Passed + .. code-block:: bash -10. Generate code coverage report and check unit tests pass:: + conda info -e - $ make test # Automatically opens HTML report in your browser - $ pytest # Does not automatically open HTML report in your browser +To return to your root environment: - ================================= test session starts ================================= - platform darwin -- Python 3.8.8, pytest-6.2.2, py-1.10.0, pluggy-0.13.1 - rootdir: , configfile: setup.cfg - plugins: anyio-2.2.0, cov-2.11.1 - collected 3 items + .. code-block:: bash - tests/test_dataset.py .. - tests/test_xcdat.py . + conda deactivate - ---------- coverage: platform darwin, python 3.8.8-final-0 ----------- - Name Stmts Miss Cover - --------------------------------------- - xcdat/__init__.py 3 0 100% - xcdat/dataset.py 18 0 100% - xcdat/xcdat.py 0 0 100% - --------------------------------------- - TOTAL 21 0 100% - Coverage HTML written to dir tests_coverage_reports/htmlcov - Coverage XML written to file tests_coverage_reports/coverage.xml +See the full `conda docs here`_. - - The Coverage HTML report is much more detailed (e.g., exact lines of tested/untested code) +.. _Miniforge: https://github.com/conda-forge/miniforge +.. _Anaconda: https://www.anaconda.com/download +.. _Miniconda: https://docs.conda.io/projects/miniconda/en/latest/ +.. _repository: https://github.com/xCDAT/xcdat +.. _conda docs here: http://conda.pydata.org/docs -11. Commit your changes:: +.. _install pre-commit hooks: - $ git add . - $ git commit -m +Install pre-commit hooks +~~~~~~~~~~~~~~~~~~~~~~~~ - Trim Trailing Whitespace.................................................Passed - Fix End of Files.........................................................Passed - Check Yaml...............................................................Passed - black....................................................................Passed - isort....................................................................Passed - flake8...................................................................Passed - mypy.....................................................................Passed +We highly recommend that you setup `pre-commit`_ hooks to automatically run all +the tools listed in the :ref:`code-formatting` section every time you make a git commit. -12. Make sure pre-commit QA checks pass. Otherwise, fix any caught issues. +To install the hooks - - Most of the tools fix issues automatically so you just need to re-stage the files. - - flake8 and mypy issues must be fixed automatically. +.. code-block:: bash -13. Push changes:: + >>> python -m pip install pre-commit + >>> pre-commit install - $ git push origin +This can be done by running: -14. Submit a pull request through the GitHub website. +.. code-block:: bash + >>> pre-commit run -Pull Request Guidelines ------------------------ +from the root of the ``xcdat`` repository. You can skip the pre-commit checks with +``git commit --no-verify``. -Before you submit a pull request, check that it meets these guidelines: +Note, these hooks are also executed in the GitHub CI/CD build workflow and must +pass before pull requests can be merged. -1. The pull request should include tests for new or modified code. -2. Link issues to pull requests. -3. If the pull request adds functionality, the docs should be updated. Put - your new functionality into a function with a docstring, and add the - feature to the list in README.rst. -4. Squash and rebase commits for a clean and navigable Git history. +Contributing to the code base +----------------------------- -When you open a pull request on GitHub, there is a template available for use. +.. contents:: + :local: +Pull request (PR) +~~~~~~~~~~~~~~~~~ -Style Guide ------------ +When you open a `pull request`_ on GitHub, there a template with a checklist available to use. -xCDAT integrates the Black code formatter for code styling. If you want to learn more, please read about it `here `__. +Here's a simple checklist for PRs: -xCDAT also leverages `Python Type Annotations `_ to help the project scale. -`mypy `_ performs optional static type checking through pre-commit. +- **Properly comment and document your code.** API docstrings are formatted using the + `NumPy style guide`_ +- **Test that the documentation builds correctly** by typing ``make docs`` in the root of the ``xcdat`` directory. This is not strictly necessary, but this may be easier than waiting for CI to catch a mistake. +- **Test your code**. -Testing -------- + - Write new tests if needed. + - Test the code using `Pytest`_. Running all tests (type ``make test`` or ``pytest`` in the root directory) takes a while, so feel free to only run the tests you think are needed based on your PR (example: ``pytest tests/test_dataset.py``). CI will catch any failing tests. -Testing your local changes are important to ensure long-term maintainability and extensibility of the project. -Since xCDAT is an open source library, we aim to avoid as many bugs as possible from reaching the end-user. +- **Properly format your code** and verify that it passes the formatting guidelines set by `Black`_ and `Flake8`_. + You can use `pre-commit`_ to run these automatically on each commit. -To get started, here are guides on how to write tests using pytest: + - Run ``pre-commit run --all-files`` in the root directory. This may modify some files. Confirm and commit any formatting changes. -- https://docs.pytest.org/en/latest/ -- https://docs.python-guide.org/writing/tests/#py-test +- **Push your code** and `create a PR on GitHub`_. +- **Use a helpful title for your pull request** by summarizing the main contributions rather than using the latest commit message. If the PR addresses a `GitHub Issue`_, please `reference it`_. -In most cases, if a function is hard to test, it is usually a symptom of being too complex (high cyclomatic-complexity). +.. _code-formatting: -DOs for Testing +Code formatting ~~~~~~~~~~~~~~~ -* *DO* write tests for new or refactored code -* *DO* try to follow test-driven-development -* *DO* use the Coverage reports to see lines of code that need to be tested -* *DO* focus on simplistic, small, reusable modules for unit testing -* *DO* cover as many edge cases as possible when testing - -DON'Ts for Testing -~~~~~~~~~~~~~~~~~~ - -* *DON'T* push or merge untested code -* *DON'T* introduce tests that fail or produce warnings - -Documenting Code ----------------- - -If you are using VS code, the `Python Docstring Generator `_ extension can be used to auto-generate a docstring snippet once a function/class has been written. -If you want the extension to generate docstrings in Sphinx format, you must set the ``"autoDocstring.docstringFormat": "sphinx"`` setting, under File > Preferences > Settings. - -Note that it is best to write the docstrings once you have fully defined the function/class, as then the extension will generate the full docstring. -If you make any changes to the code once a docstring is generated, you will have to manually go and update the affected docstrings. - -More info on docstrings here: https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html - -DOs for Documenting Code -~~~~~~~~~~~~~~~~~~~~~~~~ - -* *DO* explain **why** something is done, its purpose, and its goal. The code shows **how** it is done, so commenting on this can be redundant. -* *DO* explain ambiguity or complexities to avoid confusion -* *DO* embrace documentation as an integral part of the overall development process -* *DO* treat documenting as code and follow principles such as *Don't Repeat Yourself* and *Easier to Change* - -DON'Ts for Documenting Code -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -* *DON'T* write comments as a crutch for poor code -* *DON'T* comment *every* function, data structure, type declaration - -Developer Tips --------------- - -* flake8 will warn you if the cyclomatic complexity of a function is too high. +xCDAT uses several tools to ensure a consistent code format throughout the project: + +- `Black`_ for standardized code formatting +- `Flake8`_ for code linting +- `isort`_ for standardized order of imports +- `mypy`_ for static type checking on `type hints`_ + +We highly recommend that you setup `pre-commit hooks`_ to automatically run all the +above tools every time you make a git commit. Check out the :ref:`install pre-commit +hooks` section above for instructions. + +.. _pull request: https://github.com/xCDAT/xcdat/compare +.. _create a PR on GitHub: https://help.github.com/en/articles/creating-a-pull-request +.. _reference it: https://help.github.com/en/articles/autolinked-references-and-urls +.. _NumPy style guide: https://numpydoc.readthedocs.io/en/latest/format.html +.. _pre-commit: https://pre-commit.com/ +.. _pre-commit hooks: https://pre-commit.com/ +.. _Pytest: http://doc.pytest.org/en/latest/ +.. _Black: https://black.readthedocs.io/en/stable/ +.. _Flake8: https://flake8.pycqa.org/en/latest/ +.. _isort: https://pycqa.github.io/isort/ +.. _mypy: http://mypy-lang.org/ +.. _type hints: https://docs.python.org/3/library/typing.html + +Testing with continuous integration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - * https://github.com/PyCQA/mccabe +The xCDAT `build workflow`_ runs the test suite automatically via the `GitHub Actions`_, +continuous integration service, once your pull request is submitted. +A pull-request will be considered for merging when you have an all 'green' build. If any +tests are failing, then you will get a red 'X', where you can click through to see the +individual failed tests. This is an example of a green build. -Helpful Commands ----------------- +.. image:: _static/ci.png .. note:: - Run ``make help`` in the root of the project for a list of useful commands -To run a subset of tests:: + Each time you push to your PR branch, a new run of the tests will be + triggered on the CI. If they haven't already finished, tests for any older + commits on the same branch will be automatically cancelled. -$ pytest tests.test_xcdat +.. _build workflow: https://github.com/xCDAT/xcdat/actions/workflows/build_workflow.yml +.. _GitHub Actions: https://docs.github.com/en/free-pro-team@latest/actions -FAQs ----- +Writing tests +~~~~~~~~~~~~~ -.. _Why squash and rebase?: +All tests should go into the ``tests`` subdirectory of the specific package. +This folder contains many current examples of tests, and we suggest looking to these for +inspiration. -Why squash and rebase commits? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The ``xarray.testing`` module has many special ``assert`` functions that +make it easier to make statements about whether DataArray or Dataset objects are +equivalent. The easiest way to verify that your code is correct is to +explicitly construct the result you expect, then compare the actual result to +the expected correct result:: -Before you merge a support branch back into ``main``, the branch is typically squashed down to a single buildable commit, and then rebased on top of the main repo's ``main`` branch. + def test_constructor_from_0d(): + expected = Dataset({None: ([], 0)})[None] + actual = DataArray(0) + assert_identical(expected, actual) -Why? -* Ensures build passes from the commit -* Cleans up Git history for easy navigation -* Makes collaboration and review process more efficient -* Makes handling conflicts from rebasing simple since you only have to deal with conflicted commits - - -How do I squash and rebase commits? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -* Use GitHub's Squash and Merge feature in the pull request - - * You still need to rebase on the latest ``main`` if ``main`` is ahead of your branch. - -* Manually squash and rebase - - 1. `` Sync your fork of ``main`` (aka ``origin``) with the root ``main`` (aka ``upstream``) :: - - git checkout main - git rebase upstream/main - git push -f origin main - - 2. Get the SHA of the commit OR number of commits to rebase to :: - - git checkout - git log --graph --decorate --pretty=oneline --abbrev-commit - - 3. Squash commits:: +Developer tips +-------------- - git rebase -i [SHA] +Helpful commands +~~~~~~~~~~~~~~~~ - # OR +.. note:: + * Run ``make help`` in the root of the project for a list of useful commands + * Run ``make install`` to install a local build of xCDAT into your conda environment + * Run ``make clean`` to delete all build, test, coverage and Python artifacts - git rebase -i HEAD~[NUMBER OF COMMITS] +xCDAT and Visual Studio Code +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - 4. Rebase branch onto ``main`` :: +We recommend using `VS Code`_ as your code editor because it is open-source and has +great Python development support. - git rebase main - git push -f origin +xCDAT includes a `VS Code Workspace file`_, which conveniently configures VS Code for +quality assurance tools, code line-length rulers, and more. You just need to open this +file using VS Code, create your development environment, and select the appropriate +Python interpreter for the workspace (from the dev environment). - 5. Make sure your squashed commit messages are refined +Some recommended extensions include: - 6. Force push to remote branch :: + * `Python `_ + * `Pylance `_ + * `Python Docstring Generator `_ + * `Python Type Hint `_ + * `Better Comments `_ + * `Jupyter `_ + * `Visual Studio Intellicode `_ + * `autoDocstring `_ - git push -f origin +.. _VS Code: https://code.visualstudio.com +.. _VS Code Workspace file: https://github.com/xCDAT/xcdat/blob/main/.vscode/xcdat.code-workspace diff --git a/docs/_static/ci.png b/docs/_static/ci.png new file mode 100644 index 00000000..ad29c376 Binary files /dev/null and b/docs/_static/ci.png differ diff --git a/docs/_static/github-fork-button.png b/docs/_static/github-fork-button.png new file mode 100644 index 00000000..98698793 Binary files /dev/null and b/docs/_static/github-fork-button.png differ diff --git a/docs/getting-started-guide/installation.rst b/docs/getting-started-guide/installation.rst index a78df825..a51d4df2 100644 --- a/docs/getting-started-guide/installation.rst +++ b/docs/getting-started-guide/installation.rst @@ -7,64 +7,83 @@ Installation Prerequisites ------------- -1. Familiarity with ``xarray``, since this package is an extension of it +1. Familiarity with ``xarray`` - - We highly recommend visiting the `xarray tutorial`_ and `xarray documentation`_ - pages if you aren't familiar with ``xarray``. + We highly recommend visiting the `xarray tutorial`_ and `xarray documentation`_ + pages if you aren't familiar with ``xarray``. -2. xCDAT is distributed through the `conda-forge`_ channel of Anaconda. We recommend - using Mamba (via `Miniforge`_), a drop-in replacement of Conda that is faster and more - reliable than Conda. Miniforge ships with ``conda-forge`` set as the prioritized channel. - Mamba also uses the same commands and configurations as Conda, and you can swap - commands between both tools. +2. xCDAT is distributed through conda, which is available through Anaconda and Miniconda. - Follow these steps to install Miniforge (Mac OS & Linux): + We recommend following the `Quick command line install`_ steps in the Anaconda docs + to install Miniconda. Those steps are also provided below for convenience. .. code-block:: bash - curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh" - bash Miniforge3-$(uname)-$(uname -m).sh + >>> # Linux + >>> mkdir -p ~/miniconda3 + >>> curl https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh -o ~/miniconda3/miniconda.sh + >>> bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3 + >>> rm -rf ~/miniconda3/miniconda.sh - Then follow the instructions for installation. We recommend you type ``yes`` in - response to ``"Do you wish the installer to initialize Miniforge by running conda init?"`` - to add ``conda`` and ``mamba`` to your path. Note that this will modify your shell - profile (e.g., ``~/.bashrc``). + .. code-block:: bash + + >>> # MacOS + >>> mkdir -p ~/miniconda3 + >>> wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda3/miniconda.sh + >>> bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3 + >>> rm -rf ~/miniconda3/miniconda.sh + + Then follow the instructions for installation. To have conda added to + your path you will need to type ``yes`` in response to ``"Do you wish the + installer to initialize Miniconda3 by running conda init?"`` (we recommend + that you do this). Note that this will modify your shell profile (e.g., + ``~/.bashrc``) to add ``conda`` to your path. + + .. note:: + After installation completes you may need to type ``bash`` to + restart your shell (if you use bash). Alternatively, you can log out and + log back in. + +3. Add the ``conda-forge`` channel. + + xCDAT is hosted on the `conda-forge`_ channel, which is the standard channel for + most scientific Python packages. + + .. code-block:: bash - *Note: After installation completes you may need to type ``bash`` to - restart your shell (if you use bash). Alternatively, you can log out and - log back in.* + >>> conda config --add channels conda-forge + >>> conda config --set channel_priority strict .. _xarray tutorial: https://tutorial.xarray.dev/intro.html .. _xarray documentation: https://docs.xarray.dev/en/stable/getting-started-guide/index.html +.. _Quick command line install: https://docs.anaconda.com/free/miniconda/#quick-command-line-install .. _conda-forge: https://anaconda.org/conda-forge/xcdat -.. _Miniforge: https://github.com/conda-forge/miniforge Instructions ------------ -1. Create a Mamba environment from scratch with ``xcdat`` (`mamba create`_) +1. Create a Conda environment from scratch with ``xcdat`` (`conda create`_) - We recommend using the Mamba environment creation procedure to install ``xcdat``. - The advantage with following this approach is that Mamba will attempt to resolve - dependencies (e.g. ``python >= 3.8``) for compatibility. + We recommend using the Conda environment creation procedure to install ``xcdat``. + The advantage with following this approach is that Conda will attempt to resolve + dependencies (e.g. ``python >= 3.9``) for compatibility. - To create an ``xcdat`` Mamba environment, - run: + To create an ``xcdat`` Conda environment, run: .. code-block:: bash - >>> mamba create -n -c conda-forge xcdat - >>> mamba activate + >>> conda create -n -c conda-forge xcdat + >>> conda activate -2. Install ``xcdat`` in an existing Mamba environment (`mamba install`_) +2. Install ``xcdat`` in an existing Conda environment (`conda install`_) - You can also install ``xcdat`` in an existing Mamba environment, granted that Mamba + You can also install ``xcdat`` in an existing Conda environment, granted that Conda is able to resolve the compatible dependencies. .. code-block:: bash - >>> mamba activate - >>> mamba install -c conda-forge xcdat + >>> conda activate + >>> conda install -c conda-forge xcdat 3. [Optional] Some packages that are commonly used with ``xcdat`` can be installed either in step 1 or step 2 above: @@ -72,10 +91,11 @@ Instructions - ``jupyterlab``: a web-based interactive development environment for notebooks, code, and data. This package also includes ``ipykernel``. - ``matplotlib``: a library for creating visualizations in Python. + - ``nc-time-axis`` is an optional dependency required for ``matplotlib`` to plot ``cftime`` coordinates - ``cartopy``: an add-on package for ``matplotlib`` and specialized for geospatial data processing. -.. _mamba create: https://mamba.readthedocs.io/en/latest/user_guide/mamba.html#quickstart -.. _mamba install: https://mamba.readthedocs.io/en/latest/user_guide/mamba.html#quickstart +.. _conda create: https://docs.conda.io/projects/conda/en/latest/commands/create.html +.. _conda install: https://docs.conda.io/projects/conda/en/latest/commands/install.html Updating -------- @@ -85,15 +105,16 @@ latest stable version of ``xcdat`` for the latest features and bug fixes. .. code-block:: bash - >>> mamba activate - >>> mamba update xcdat + >>> conda activate + >>> conda update xcdat To update to a specific version of ``xcdat``: .. code-block:: bash - >>> mamba activate - >>> mamba update xcdat= + >>> conda activate + >>> conda update xcdat= + >>> # Example: conda update xcdat=0.6.1 Jupyter Users set ``ESMFMKFILE`` env variable --------------------------------------------- diff --git a/xcdat/dataset.py b/xcdat/dataset.py index 45774b48..32522bd6 100644 --- a/xcdat/dataset.py +++ b/xcdat/dataset.py @@ -225,7 +225,6 @@ def open_mfdataset( ---------- .. [2] https://docs.xarray.dev/en/stable/generated/xarray.combine_nested.html .. [3] https://xarray.pydata.org/en/stable/generated/xarray.open_mfdataset.html - .. [4] https://cdms.readthedocs.io/en/latest/manual/cdms_6.html """ if isinstance(paths, str) or isinstance(paths, pathlib.Path): if os.path.isdir(paths):