Improved environment management docs (#71)

* improved environment docs

Author: scottyhq

.github/workflows/qaqc.yaml

@@ -24,7 +24,7 @@ jobs:
         with:
           check_filenames: true
           check_hidden: true
-          skip: '*.js,qaqc.yml'
+          skip: '.git,*.js,qaqc.yml'
           ignore_words_list: hist,nd
 
       # borrowed from https://github.com/ProjectPythia/pythia-foundations/blob/main/.github/workflows/link-checker.yaml

.prettierignore

@@ -0,0 +1 @@
+*lock.yml

CONTRIBUTING.md

@@ -0,0 +1,71 @@
+## Contributing
+
+This repository is a great opportunity to start contributing to Xarray.
+
+- Report bugs, request features or submit feedback as a [GitHub Issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues). First check existing issues: https://github.com/xarray-contrib/xarray-tutorial/issues !
+
+- Make fixes, add content or improvements using [GitHub Pull Requests](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests), the sections below go over this process in more detail:
+
+## Content Guidelines
+
+Please note that examples submitted to this repository should follow these
+guidelines:
+
+1. Run top-to-bottom without intervention from the user
+1. Not require external data sources that may disappear over time (external data sources that are highly unlikely to disappear are fine)
+1. Not be resource intensive, and should run within 2GB of memory
+1. Be clear and contain enough prose to explain the topic at hand
+1. Be concise and limited to one or two topics, such that a reader can get through the example within a few minutes of reading
+1. Be of general relevance to Xarray users, and so not too specific on a particular problem or use case.
+
+## Fork this repository
+
+We recommend first forking this repository and creating a local copy:
+
+```
+git clone https://github.com/YOURACCOUNT/xarray-tutorial.git
+cd xarray-tutorial
+```
+
+## Create a Python environment
+
+You'll need `conda` or `mamba`, which can be installed from https://github.com/conda-forge/miniforge
+
+We also use [conda-lock](https://conda-incubator.github.io/conda-lock/) to ensure we have reproducible environments across different operating systems
+
+We also use [pre-commit hooks](https://pre-commit.com) to run styling and other checks before committing code.
+
+```
+conda-lock install -f conda/conda-lock.yml
+# Or latest package versions: `mamba env create -f conda/environment-unpinned.yml`
+
+conda activate xarray-tutorial
+
+pre-commit install
+```
+
+## Add content
+
+Develop your new content on a branch. See [JupyterBook Docs](https://jupyterbook.org/en/stable/intro.html) for guides on adding `.md`, `.ipynb` and other content.
+
+```
+git checkout -b newcontent
+git add .
+git commit -m "added pages x,y and improved z"
+```
+
+## Preview your changes
+
+Running jupyterbook will execute notebooks and render HTML pages for the website. Be sure to fix any execution errors and preview the website in your web browser to make sure everything looks good!
+
+```
+jb build .
+```
+
+## Open a pull request
+
+```
+git push
+```
+
+Follow the link reported in a terminal to open a pull request!

README.md

@@ -1,26 +1,34 @@
-# Xarray Example Notebooks
+# Xarray Tutorial
 
 [![CI](https://github.com/xarray-contrib/xarray-tutorial/workflows/CI/badge.svg?branch=main)](https://github.com/xarray-contrib/xarray-tutorial/actions?query=branch%3Amain)
+[![Jupyter Book Badge](https://jupyterbook.org/badge.svg)](https://tutorial.xarray.dev)
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/xarray-contrib/xarray-tutorial/HEAD?urlpath=lab)
 
-This repository includes easy-to-run example notebooks for Xarray.
-They are intended to be educational and give users a start on common workflows.
+This is the repository for a JupyterBook website with tutorial material for [Xarray](https://github.com/pydata/xarray), _an open source project and Python package that makes working with labelled multi-dimensional arrays simple, efficient, and fun!_
 
-They should be easy to run locally if you download this repository.
-They are also available on the cloud by clicking on the link below:
+The website is hosted at https://tutorial.xarray.dev
 
-[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/xarray-contrib/xarray-tutorial/HEAD?urlpath=lab)
+Tutorials are written as interactive Jupyter Notebooks with executable code examples that you can easily run and modify:
 
-## Contributing
+#### On the Cloud
+
+All notebooks can be run via the Mybinder.org 'Launch Binder' badge at the top of this page. This will load a pre-configured JupyterLab interface with all tutorial notebooks for you to run. _You have minimal computing resources and any changes you make will not be saved._
+
+#### Locally
 
-This repository is a great opportunity to start contributing to Xarray.
-Please note that examples submitted to this repository should follow these
-guidelines:
+You can also run these notebooks on your own computer! We recommend using [`conda-lock`](https://conda-incubator.github.io/conda-lock/) to ensure a fully reproducible Python environment:
 
-1. Run top-to-bottom without intervention from the user
-2. Not require external data sources that may disappear over time (external data sources that are highly unlikely to disappear are fine)
-3. Not be resource intensive, and should run within 2GB of memory
-4. Be clear and contain enough prose to explain the topic at hand
-5. Be concise and limited to one or two topics, such that a reader can get through the example within a few minutes of reading
-6. Be of general relevance to Xarray users, and so not too specific on a particular problem or use case.
+```bash
+git clone https://github.com/xarray-contrib/xarray-tutorial.git
+cd xarray-tutorial
+
+conda-lock install -f conda/conda-lock.yml --name xarray-tutorial
+# Or latest package versions: `mamba env create -f conda/environment-unpinned.yml`
+
+conda activate xarray-tutorial
+jupyter lab
+```
+
+## Contributing
 
-_Note: Some of the content in this repository came from a similar projects: https://github.com/dask/dask-tutorial_
+Contributions are welcome and greatly appreciated! See our [CONTRIBUTING.md](./CONTRIBUTING.md) document.

conda/README.md

@@ -18,7 +18,7 @@ conda-lock install
 ## Create/update multiplatform lockfile:
 
 ```
-conda-lock lock --mamba -f environment-unpinned.yml -p osx-64 -p linux-64 -p win-64
+conda-lock lock --mamba -f environment-unpinned.yml -p osx-64 -p linux-64 -p win-64 -p osx-arm64
 ```
 
 ## Render a mybinder.org compatible locked file