DOCS: create how-to page on environments with hatch

[lwasser]

This pr attempts to address:

• How to enter and exit a hatch environment (and how to know what envt the current shell is in). #1207
• does hatch have a way to create a shell in the non default environment? #431

@ofek i missed the configuration section when initially reading this so i tried to add links to that section as well. I"m really happy to edit / fix etc if this isn't inline with what you want for the docs. I left a few questions using html comments in the text which will help me clarify a bit more. i'll also post this pr in the discussions in case that's helpful for others searching

Finally - this is my first time contributing here and my first time dealing with mkdocs so feel free to let me know if i did things incorrectly or if there is a way to make things easier for you to review.

[ofek]

Thank you! What do you think about leaving this page mostly untouched and instead create a new docs/how-to/environment/PAGE_NAME.md? Context: #1123 (comment)

Examples:

• Add how-to page for customizing static analysis #1185
• https://github.com/pypa/hatch/pull/789/files#diff-5c25e8fa6c85befb89240079a8a464ff31c7ba62fd39841067cc7ee7744cbf8d

[lwasser]

@ofek i'm happy to help with tutorials and to migrate this to a tutorial/how to page.
i have a few questions however!

• how is the "walk through" in this section different from a tutorial in your mind?
• Would we then link to the tutorial / how to from this existing walk-through page?

i guess one thing i'm a bit worried about is you have a page dedicated to environments and then another tutorial page on environments. it could get confusing for a user to have to look at both pages but if things are clearly linked it could be ok and i'm happy to work on it either way once i understand the plan!

[ofek]

• This walkthrough I imagine as a very high level introduction where we wouldn't enumerate many options. I would imagine how-to documents are more targeted toward use cases and solving particular goals. I plan to reorganize the documentation eventually to go all in to this: https://diataxis.fr
• Yes definitely feel free to link elsewhere, the documentation does that quite a bit!

[lwasser]

ok great - give me a few days - i'll refactor this PR and turn it into a how-to with links from that environment page!

[DahanDv]

Hey @ofek ,
I was looking to commit to the DOCS improvement suggestion and ran into this PR (and all the relevant discussions you pointed to).
As I'm almost in the same spot as @lwasser, looking to contribute and improve the docs, I have two questions:

1. If diataxis becomes the de facto standard for documenting this project,
   how about we create a concise how-to-document guide?
   (I was thinking about a TL;DR version for diataxis, i.e., some general guidelines to follow, Do's and Don'ts), so aspiring contributors would be able to follow and know in advance that their work is at par with your plans and standards.
   What do you think? I'd love to help on this one.
   Once we have this set in place, you can open issues "create how to guide to X" and assign them to contributors, and we'll be more efficient and satisfied with our work.

2. regardless of (1), I'm looking to improve the docs around hatch Python version management (I have in my head something more tutorial-style - if we already speak in terms of diataxis). Will this contribution be welcomed, or do you already have something you work on in this area? (you stated your intention to "refactor" all the docs).

I hope you find reason in my suggestions.

[lwasser]

hey @DahanDv 👋 are you thinking that we could create a meta issue perhaps with an outline of the pages the @ofek and the community could use. and then we could open issues as contributors to tackle items? That way ofek could guide contributors through what is needed and what he's like to see and we could more effectively contribute?

i would find that useful as a new contributor. i just contributed to the envt page (which will become a how to once i work on this more) because i was trying to understand environments and noticed others had the same questions that i did. hatch provides a different model. it's actually really nice now that i understand how it works. it's just different from what i'm used to in Python.

[DahanDv]

@lwasser Hey there!
I was thinking about a somewhat evergreen supplement to the contributing guide for this project, that explains the documentation standards that Ofek wants. (I hope I understood your question 😬)

Regarding your suggestion about meta issue:
Since refactoring and expanding the docs will include lots of individual tasks, meta issue sounds to me like the best tool for the job. I admit I didn't think about it.
The idea is giving @ofek an efficient way to distribute the tasks and enforce his standards with minimum friction in the process.
Let's see what he says about it all. 🙂

[ofek]

Thank you both for the discussion, great stuff! I do like the idea of a meta issue. Additionally, I should add a contributing section to the docs that has a page for code, documentation, and releasing (for maintainers).

I do plan on adhering to that documentation framework more and tutorials will be necessary. If you wouldn't mind creating a tutorial for version management as you mentioned that would be awesome!

Could one of you perhaps please create the meta issue where we can enumerate the initial planned how-to pages? After I get a sense of what it looks like I can turn it into a GitHub project for tracking.

[DahanDv]

Thank you @ofek !

Additionally, I should add a contributing section to the docs that has a page for code, documentation, and releasing (for maintainers).

Just to make sure my interpretation is correct:
you wish to create the documentation-contribution guide yourself?
If I misunderstood, I'd love to suggest a draft for it as I described earlier in this discussion.

If you wouldn't mind creating a tutorial for version management as you mentioned that would be awesome!

yes I'd love to deliver this Python version management tutorial. Assign me on this once you have the tracking tool (meta issue/project) in place!

Could one of you perhaps please create the meta issue where we can enumerate the initial planned how-to pages? After I get a sense of what it looks like I can turn it into a GitHub project for tracking.

Great!
@lwasser, would you like to pick up the meta issue creation? I've never done this before, and it was your idea :)

[lwasser]

@ofek or anyone - i can't figure out how to launch into a shell for a specific environment such as test. i tried

hatch shell test

hatch run test:shell (doesn't make sense but tried it)

hatch -e test shell

how do i get a user into their test shell in case they want to do some work at the CLI in that envt?

thank you!

[ofek]

The one you mentioned works hatch -e test shell

[lwasser]

it does. @ofek i'm going to work on it a bit more tonight. i must have been tired last night hatch -e test shell works.

[lwasser]

hi 👋 @DahanDv @ofek sure - i can work on the meta issue this week. Essentially we can create a structure of content that will hit the basic user needs in terms of tutorials and how tos (i find these two types of content to be tricky sometimes to distinguish between :) ). And then from that issue (i'm sure we will have a lot of back and forth but i'll keep the first comment updated with the latest desired structure, we can create individual issue / tasks that can be assigned to specific people (or even can be flagged with help-wanted labels to direct users to what is needed.

in the meantime - i could use a review of this current how-to if either of you have time! ✨ i didn't add anything on cleanup / pruning environments.

and specifically i could not figure out how to "spawn" a shell for a specific environment. hatch shell test runs but i was surprised as it didn't have pytest in it when i ran pip list.

pyosPackage (☊ main) [✎ ×1 ] is 📦 v0.1.4 via 🐍 pyenv (pyospackage) 
❯ hatch shell test
Already in environment: default

pyosPackage (☊ main) [✎ ×1 ] is 📦 v0.1.4 via 🐍 pyenv (pyospackage) 
❯ exit

pyosPackage (☊ main) [✎ ×1 ] is 📦 v0.1.4 via 🐍 pyenv took 53s 
❯ hatch shell test
source ".../path/hatch/env/virtual/pyospackage/twO2iQR3/pyospackage/bin/activate"

pyosPackage (☊ main) [✎ ×1 ] is 📦 v0.1.4 via 🐍 pyenv 
➜ source ".../path/hatch/env/virtual/pyospac
kage/twO2iQR3/pyospackage/bin/activate"

pyosPackage (☊ main) [✎ ×1 ] is 📦 v0.1.4 via 🐍 pyenv (pyospackage) 
➜ pytest
zsh: command not found: pytest

many thanks!

[DahanDv]

@lwasser Are you running the latest version of Hatch?
I have another column in this table: "Scripts"
Did you remove it for simplicity?
From a diataxis POV, this can trigger anxiety for beginners trying to follow and observe unexplained delta from the how-to.
It's small but worth thinking of.
Consider this :)

[lwasser]

I am! 1.9.3.

so @DahanDv please note that the output of all of this depends on the pyproject.toml file that a user begins with.

If a user is migrating to hatch they may or may not have that full verbose pyproject.toml that you get with the default hatch init. Further, if your config is setup in a way that excludes test matrices when you run hatch init then it also won't have those additional columns / matrix setup.

because in a how-to file, I dont think we can assume a specific user entry point/ I'd rather keep things simple. BUT perhaps it's worth adding a breakout to note your point above about how you may get different results depending upon how you begin to use hatch. In the tutorials we are creating for pyOpenSci we are leading the user through all of the steps and suggesting they won't start with the matrix envt / more complex pyproject.toml just to decrease cognitive load at the beginning. But we will introduce it later. I think for a tutorial exploring all of the ins and outs is a good idea but a how-to should be more concise just giving a user how to do x,y,z without assumptions.

my two cents :)

[ofek]

I added:

Note

The output may have more columns depending on your environment configuration.

[DahanDv]

You made a super important point that hatch will go to default env unless told otherwise.
But I would rather use an example that "proves" this in a negative way. To get verbose feedback.
i.e., calling a script defined from another env or calling a pip list from another env with different dependencies.

Since this is about making a point that is true to ALL usages of the env feature, I think this is a point to make in a tutorial.
Emphasizing that how-to is for specific purposes to accomplish - like you did with the examples of isolated test env.

(I know I'm being pedantic ignore me if it's too much - it's Ofek's call anyways)

[lwasser]

hi there @DahanDv my understand is this is a how-to not a tutorial. as such i think we just want to show people here how to do things rather than a tutorial that might explore various things that work and don't work. i'm definitely open to feedback but based on what @ofek linked to i how to's are more to the point - how to do this thing well.

i'm of course open to discussion.

[ofek]

I moved to this to a brand-new tutorial section since yes I think how-to documents should be more targeted.

[jhossbach]

and specifically i could not figure out how to "spawn" a shell for a specific environment. hatch shell test runs but i was surprised as it didn't have pytest in it when i ran pip list.

pyosPackage (☊ main) [✎ ×1 ] is 📦 v0.1.4 via 🐍 pyenv (pyospackage) 
❯ hatch shell test
Already in environment: default

pyosPackage (☊ main) [✎ ×1 ] is 📦 v0.1.4 via 🐍 pyenv (pyospackage) 
❯ exit

pyosPackage (☊ main) [✎ ×1 ] is 📦 v0.1.4 via 🐍 pyenv took 53s 
❯ hatch shell test
source ".../path/hatch/env/virtual/pyospackage/twO2iQR3/pyospackage/bin/activate"

pyosPackage (☊ main) [✎ ×1 ] is 📦 v0.1.4 via 🐍 pyenv 
➜ source ".../path/hatch/env/virtual/pyospac
kage/twO2iQR3/pyospackage/bin/activate"

pyosPackage (☊ main) [✎ ×1 ] is 📦 v0.1.4 via 🐍 pyenv (pyospackage) 
➜ pytest
zsh: command not found: pytest

I have the same issue and came upon this PR, so I think this is the right place to ask, but is this unwanted behavior? Specifically in the docs it says hatch shell [OPTIONS] [SHELL_NAME] [SHELL_PATH] [SHELL_ARGS]... but giving a shell name here still activates the default shell. Also, what are the [SHELL_ARGS]...?

[lwasser]

jhossbach

Hey @jhossbach 👋 try this:

➜ hatch -e test shell
source "/Users/leahawasser/Library/Application Support/hatch/env/virtual/pyospackage/Fw213C8y/test/bin/activate"

pyosPackage (☊ main) [✎ ×1 ?] is 📦 v0.1.10 via 🐍 pyenv 
➜ source "/Users/leahawasser/Library/Application Support/
hatch/env/virtual/pyospackage/Fw213C8y/test/bin/activate"


pyosPackage (☊ main) [✎ ×1 ?] is 📦 v0.1.10 via 🐍 pyenv (test) 
➜ pytest
================== test session starts ==================
platform darwin -- Python 3.12.1, pytest-8.0.0, pluggy-1.4.0
rootdir: /my/path/GitHub/pyos/pyospackage
plugins: cov-4.1.0
collected 0 items                                       

================= no tests ran in 0.01s =================

pyosPackage (☊ main) [✎ ×1 ?] is 📦 v0.1.10 via 🐍 pyenv (test) 
❯ pip list
Package     Version Editable project location
----------- ------- ----------------------------------------------------
coverage    7.4.1
iniconfig   2.0.0
packaging   23.2
pip         23.3.1
pluggy      1.4.0
pyospackage 0.1.10  /path/GitHub/pyos/pyospackage
pytest      8.0.0
pytest-cov  4.1.0

I was doing the same thing as you. hatch -e tells hatch to access a specific environment

so it's

hatch -e envt-name shell

i've updated this how-to with that information and things are working well now! :) soon to be added to the docs!

[lwasser]

ok @ofek can you (when you have time) please review this again. my apologies for the delay - life got busy. but i didn't forget about this. :)

i can also work on an issue where we can iterate with @DahanDv and whomever else wishes to work on this! i'll also - as i work on things try to find issues related to them to pull in the people opening issues into reviewing the how-to and tutorial items that we add!!

And updated contributing info / a development guide with release info would be wonderful. altho i did also find your existing contributing info to be great. i'm really enjoying hatch now that i better understand how things work.

[ofek]

I'll fix this up after dinner today and merge!

[lwasser]

ok i now understand scripts @ofek !! how cool.

i just ran build-check locally and fixed the broken link that was breaking this build. I also opened #1263 to fix a small typo in the contributing file. hopefully this will run and be all ✅ ✨

[lwasser]

tests were 🔴 so i just rebased. but it shouldn't have anything to do with this PR as it's only documentation changes.

[lwasser]

yay - ✅ !! all tests passing now. 🎉

[ofek]

Thank you for your effort here and sorry for the wait! I converted this into a tutorial (first one!) and fixed a few typos and also added cross-links to other pages.

If you feel more should be added, feel free to open up another PR 🙂