Add the mdformat pre-commit hook

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,6 +1,6 @@
 <!-- Feel free to remove check-list items aren't relevant to your change -->
 
-- [ ] Closes #xxxx
-- [ ] Tests added
-- [ ] User visible changes (including notable bug fixes) are documented in `whats-new.rst`
-- [ ] New functions/methods are listed in `api.rst`
+- \[ \] Closes #xxxx
+- \[ \] Tests added
+- \[ \] User visible changes (including notable bug fixes) are documented in `whats-new.rst`
+- \[ \] New functions/methods are listed in `api.rst`

.pre-commit-config.yaml

@@ -23,6 +23,10 @@ repos:
       - id: rst-directive-colons
       - id: rst-inline-touching-normal
       - id: text-unicode-replacement-char
+  - repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.18
+    hooks:
+    - id: mdformat
   - repo: https://github.com/astral-sh/ruff-pre-commit
     # Ruff version.
     rev: 'v0.6.9'

CODE_OF_CONDUCT.md

@@ -8,19 +8,19 @@ In the interest of fostering an open and welcoming environment, we as contributo
 
 Examples of behavior that contributes to creating a positive environment include:
 
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy towards other community members
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
 
 Examples of unacceptable behavior by participants include:
 
-* The use of sexualized language or imagery and unwelcome sexual attention or advances
-* Trolling, insulting/derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or electronic address, without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a professional setting
+- The use of sexualized language or imagery and unwelcome sexual attention or advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic address, without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
 
 ## Our Responsibilities
 

CORE_TEAM_GUIDE.md

@@ -69,7 +69,7 @@ Here’s a typical workflow for triaging a newly opened issue or discussion:
    The issue tracker is many people’s first interaction with the xarray project itself, beyond just using the library.
    It may also be their first open-source contribution of any kind. As such, we want it to be a welcoming, pleasant experience.
 
-2. **Is the necessary information provided?**
+1. **Is the necessary information provided?**
 
    Ideally reporters would fill out the issue template, but many don’t. If crucial information (like the version of xarray they used),
    is missing feel free to ask for that and label the issue with “needs info”.
@@ -79,14 +79,14 @@ Here’s a typical workflow for triaging a newly opened issue or discussion:
    Make sure that the title accurately reflects the issue. Edit it yourself if it’s not clear.
    Remember also that issues can be converted to discussions and vice versa if appropriate.
 
-3. **Is this a duplicate issue?**
+1. **Is this a duplicate issue?**
 
    We have many open issues. If a new issue is clearly a duplicate, label the new issue as “duplicate”, and close the issue with a link to the original issue.
    Make sure to still thank the reporter, and encourage them to chime in on the original issue, and perhaps try to fix it.
 
    If the new issue provides relevant information, such as a better or slightly different example, add it to the original issue as a comment or an edit to the original post.
 
-4. **Is the issue minimal and reproducible?**
+1. **Is the issue minimal and reproducible?**
 
    For bug reports, we ask that the reporter provide a minimal reproducible example.
    See [minimal-bug-reports](https://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports) for a good explanation.
@@ -98,29 +98,28 @@ Here’s a typical workflow for triaging a newly opened issue or discussion:
 
    If a reproducible example is provided, but you see a simplification, edit the original post with your simpler reproducible example.
 
-5. **Is this a clearly defined feature request?**
+1. **Is this a clearly defined feature request?**
 
    Generally, xarray prefers to discuss and design new features in issues, before a pull request is made.
    Encourage the submitter to include a proposed API for the new feature. Having them write a full docstring is a good way to pin down specifics.
 
    We may need a discussion from several xarray maintainers before deciding whether the proposal is in scope for xarray.
 
-6. **Is this a usage question?**
+1. **Is this a usage question?**
 
-   We prefer that usage questions are asked on StackOverflow with the [`python-xarray` tag](https://stackoverflow.com/questions/tagged/python-xarray
-) or as a [GitHub discussion topic](https://github.com/pydata/xarray/discussions).
+   We prefer that usage questions are asked on StackOverflow with the [`python-xarray` tag](https://stackoverflow.com/questions/tagged/python-xarray) or as a [GitHub discussion topic](https://github.com/pydata/xarray/discussions).
 
    If it’s easy to answer, feel free to link to the relevant documentation section, let them know that in the future this kind of question should be on StackOverflow, and close the issue.
 
-7. **What labels and milestones should I add?**
+1. **What labels and milestones should I add?**
 
    Apply the relevant labels. This is a bit of an art, and comes with experience. Look at similar issues to get a feel for how things are labeled.
    Labels used for labelling issues that relate to particular features or parts of the codebase normally have the form `topic-<SOMETHING>`.
 
    If the issue is clearly defined and the fix seems relatively straightforward, label the issue as `contrib-good-first-issue`.
    You can also remove the `needs triage` label that is automatically applied to all newly-opened issues.
 
-8. **Where should the poster look to fix the issue?**
+1. **Where should the poster look to fix the issue?**
 
    If you can, it is very helpful to point to the approximate location in the codebase where a contributor might begin to fix the issue.
    This helps ease the way in for new contributors to the repository.
@@ -173,7 +172,7 @@ constructive criticism on ideas and implementations, and remind
 yourself of how it felt when your own work was being evaluated as a
 novice.
 
-``xarray`` strongly values mentorship in code review.  New users
+`xarray` strongly values mentorship in code review.  New users
 often need more handholding, having little to no git
 experience. Repeat yourself liberally, and, if you don’t recognize a
 contributor, point them to our development guide, or other GitHub
@@ -186,42 +185,42 @@ an abandoned pull request.
 When reviewing, focus on the following:
 
 1. **Usability and generality:** `xarray` is a user-facing package that strives to be accessible
-to both novice and advanced users, and new features should ultimately be
-accessible to everyone using the package. `xarray` targets the scientific user
-community broadly, and core features should be domain-agnostic and general purpose.
-Custom functionality is meant to be provided through our various types of interoperability.
-
-2. **Performance and benchmarks:** As `xarray` targets scientific applications that often involve
-large multidimensional datasets, high performance is a key value of `xarray`. While
-every new feature won't scale equally to all sizes of data, keeping in mind performance
-and our [benchmarks](https://github.com/pydata/xarray/tree/main/asv_bench) during a review may be important, and you may
-need to ask for benchmarks to be run and reported or new benchmarks to be added.
-You can run the CI benchmarking suite on any PR by tagging it with the ``run-benchmark`` label.
-
-3. **APIs and stability:** Coding users and developers will make
-extensive use of our APIs. The foundation of a healthy ecosystem will be
-a fully capable and stable set of APIs, so as `xarray` matures it will
-very important to ensure our APIs are stable. Spending the extra time to consider names of public facing
-variables and methods, alongside function signatures, could save us considerable
-trouble in the future. We do our best to provide [deprecation cycles](https://docs.xarray.dev/en/stable/contributing.html#backwards-compatibility)
-when making backwards-incompatible changes.
-
-4. **Documentation and tutorials:** All new methods should have appropriate doc
-strings following [PEP257](https://peps.python.org/pep-0257/) and the
-[NumPy documentation guide](https://numpy.org/devdocs/dev/howto-docs.html#documentation-style).
-For any major new features, accompanying changes should be made to our
-[tutorials](https://tutorial.xarray.dev). These should not only
-illustrates the new feature, but explains it.
-
-5. **Implementations and algorithms:** You should understand the code being modified
-or added before approving it.  (See [Merge Only Changes You Understand](#merge-only-changes-you-understand)
-below.) Implementations should do what they claim and be simple, readable, and efficient
-in that order.
-
-6. **Tests:** All contributions *must* be tested, and each added line of code
-should be covered by at least one test. Good tests not only execute the code,
-but explore corner cases.  It can be tempting not to review tests, but please
-do so.
+   to both novice and advanced users, and new features should ultimately be
+   accessible to everyone using the package. `xarray` targets the scientific user
+   community broadly, and core features should be domain-agnostic and general purpose.
+   Custom functionality is meant to be provided through our various types of interoperability.
+
+1. **Performance and benchmarks:** As `xarray` targets scientific applications that often involve
+   large multidimensional datasets, high performance is a key value of `xarray`. While
+   every new feature won't scale equally to all sizes of data, keeping in mind performance
+   and our [benchmarks](https://github.com/pydata/xarray/tree/main/asv_bench) during a review may be important, and you may
+   need to ask for benchmarks to be run and reported or new benchmarks to be added.
+   You can run the CI benchmarking suite on any PR by tagging it with the `run-benchmark` label.
+
+1. **APIs and stability:** Coding users and developers will make
+   extensive use of our APIs. The foundation of a healthy ecosystem will be
+   a fully capable and stable set of APIs, so as `xarray` matures it will
+   very important to ensure our APIs are stable. Spending the extra time to consider names of public facing
+   variables and methods, alongside function signatures, could save us considerable
+   trouble in the future. We do our best to provide [deprecation cycles](https://docs.xarray.dev/en/stable/contributing.html#backwards-compatibility)
+   when making backwards-incompatible changes.
+
+1. **Documentation and tutorials:** All new methods should have appropriate doc
+   strings following [PEP257](https://peps.python.org/pep-0257/) and the
+   [NumPy documentation guide](https://numpy.org/devdocs/dev/howto-docs.html#documentation-style).
+   For any major new features, accompanying changes should be made to our
+   [tutorials](https://tutorial.xarray.dev). These should not only
+   illustrates the new feature, but explains it.
+
+1. **Implementations and algorithms:** You should understand the code being modified
+   or added before approving it.  (See [Merge Only Changes You Understand](#merge-only-changes-you-understand)
+   below.) Implementations should do what they claim and be simple, readable, and efficient
+   in that order.
+
+1. **Tests:** All contributions *must* be tested, and each added line of code
+   should be covered by at least one test. Good tests not only execute the code,
+   but explore corner cases.  It can be tempting not to review tests, but please
+   do so.
 
 Other changes may be *nitpicky*: spelling mistakes, formatting,
 etc. Do not insist contributors make these changes, but instead you should offer
@@ -268,8 +267,8 @@ resources such as:
 - Our [philosophy and development roadmap](https://docs.xarray.dev/en/stable/roadmap.html).
 - [PEP8](https://peps.python.org/pep-0008/) for Python style.
 - [PEP257](https://peps.python.org/pep-0257/) and the
-   [NumPy documentation guide](https://numpy.org/devdocs/dev/howto-docs.html#documentation-style)
-   for docstring conventions.
+  [NumPy documentation guide](https://numpy.org/devdocs/dev/howto-docs.html#documentation-style)
+  for docstring conventions.
 - [`pre-commit`](https://pre-commit.com) hooks for autoformatting.
 - [`ruff`](https://github.com/astral-sh/ruff) autoformatting and linting.
 - [python-xarray](https://stackoverflow.com/questions/tagged/python-xarray) on Stack Overflow.

DATATREE_MIGRATION_GUIDE.md

@@ -4,7 +4,7 @@ _15th October 2024_
 
 This guide is for previous users of the prototype `datatree.DataTree` class in the `xarray-contrib/datatree repository`. That repository has now been archived, and will not be maintained. This guide is intended to help smooth your transition to using the new, updated `xarray.DataTree` class.
 
-> [!IMPORTANT]
+> \[!IMPORTANT\]
 > There are breaking changes! You should not expect that code written with `xarray-contrib/datatree` will work without any modifications.  At the absolute minimum you will need to change the top-level import statement, but there are other changes too.
 
 We have made various changes compared to the prototype version. These can be split into three categories: data model changes, which affect the hierarchal structure itself, integration with xarray's IO backends; and minor API changes, which mostly consist of renaming methods to be more self-consistent.
@@ -26,13 +26,15 @@ Now xarray's backend entrypoint system has been generalized to include `open_dat
 This means we can now extend other xarray backends to support `open_datatree`! If you are the maintainer of an xarray backend we encourage you to add support for `open_datatree` and `open_groups`!
 
 Additionally:
+
 - A `group` kwarg has been added to `open_datatree` for choosing which group in the file should become the root group of the created tree.
 - Various performance improvements have been made, which should help when opening netCDF files and Zarr stores with large numbers of groups.
 - We anticipate further performance improvements being possible for datatree IO.
 
 ### API changes
 
 A number of other API changes have been made, which should only require minor modifications to your code:
+
 - The top-level import has changed, from `from datatree import DataTree, open_datatree` to `from xarray import DataTree, open_datatree`. Alternatively you can now just use the `import xarray as xr` namespace convention for everything datatree-related.
 - The `DataTree.ds` property has been changed to `DataTree.dataset`, though `DataTree.ds` remains as an alias for `DataTree.dataset`.
 - Similarly the `ds` kwarg in the `DataTree.__init__` constructor has been replaced by `dataset`, i.e. use `DataTree(dataset=)` instead of `DataTree(ds=...)`.