Tutorial: getting started with conda

[baharmon]

A new quick start tutorial on GRASS for Conda. Covers installing the miniforge distribution of Conda, creating an environment for GRASS and Jupyter, downloading the Natural Earth Dataset, and then displaying maps in a Jupyter Notebook. This pull request should be merged after PR #115 since it expects acm.csl to be in the root directory.

[veroandreo]

Let's omit using gisdbase and grassdata... We are trying to put projects in the spotlight and avoid the traditional directory structure. We can have projects anywhere, so perhaps just download the zip in the current directory, no need to create a grassdata for a zip file.

[baharmon]

@veroandreo Okay. gs.setup.init and gj.init require a project path though. So I think I need to include a path in the call: session = gj.init(Path.cwd() / "natural_earth_dataset"). Is there a better way?

Alternatively, we could create a temporary directory and project like in many of the other tutorials. Perhaps just using the current directory, however, is a little simpler and an example of a different way to work.

[veroandreo]

Yes, either a path to the project (and it'll start the session in PERMANENT) or a directory (be it temporary, current or grassdata) + project name, so: session = gj.init(Path.cwd(), "natural_earth_dataset"). You could also do:

home = Path.cwd()
project = "natural_earth_dataset"
session = gj.init(home, project)

[baharmon]

I like the latter; it is very clear.

[veroandreo]

Shall we wait to merge this tutorial until the conda package for Windows is ready? Or maybe we say something like "Conda package for Windows is coming soon!"?

[baharmon]

@veroandreo After some reflection, I think I'd prefer publishing this now and then updating it. I commented out the Windows instructions and replaced it with a coming soon statement. I don't know how long it will be before the Windows package is released. When GRASS 8.5 for Conda is out, I will update the tutorial to use the new GRASS Tools API. I also plan to write another, more in-depth tutorial.

[veroandreo]

Meanwhile, we now have conda package for Windows too :)

[baharmon]

I removed the citation style from this tutorial's frontmatter as it will be set in the project's yaml file. See 5fc178d.

[Valyrian-Code]

Nice, clear quickstart — the structure (Manager → Environment → Notebook) reads really well, and the {{< meta links.* >}} pattern plus format: ipynb output are great. I tested the links and the dataset download; almost everything checks out. One thing that would break the setup for a new user, and a few small suggestions:

One required fix before merge

The conda install step installs into the wrong environment.

conda create --name grass
conda install grass jupyterlab
conda activate grass

conda create --name grass creates the env but doesn't activate it, so conda install grass jupyterlab installs into the currently-active base env rather than grass. conda activate grass then switches to the still-empty env, and the later jupyter lab won't be found. Activating before installing fixes it:

conda create --name grass
conda activate grass
conda install grass jupyterlab

(The one-liner just below — conda create -n grass grass jupyterlab && conda activate grass — is already correct.)

Suggestions (non-blocking)

• grass_projects link uses grass-devel (in the frontmatter links: block). #124 moved the repo to grass-stable; the page exists on stable too, so switching keeps it consistent and stable across releases.
• requests isn't in the install list — it's imported in the notebook but only grass jupyterlab are installed. It usually comes in transitively via jupyterlab_server, but adding requests to the conda install (or using stdlib urllib.request) makes the notebook self-contained.
• Two small typos: "We will using scripting" → "We will use scripting"; "open an new Jupyter notebook" → "a new".
• date: last-modified — other tutorials use an explicit date: (plus date-modified: today); since the homepage listing sorts by date, an explicit date is a bit more predictable.

With the environment ordering fixed this is good to go from my side. Thanks for putting this together!

[baharmon]

Refactored for the GRASS Tools API.

[Valyrian-Code]

Thanks for the quick turnaround — all my earlier points are addressed (env ordering, requests, grass-stable link, typos, and the date). Nice touch refactoring to the grass.tools API too; moving off the deprecated g.proj -g flag to format="shell" matches what the manual now recommends. I checked and grass.tools is documented on grass-stable, so it'll resolve in the conda release.

One tiny, non-blocking thing: now that both gs.run_command(...) calls are tools.*, import grass.script as gs is unused and could be dropped.

LGTM otherwise — thanks for putting this together! 🎉