doc: minicline pass at improving environment docs

[satra]

Types of changes

Improve howto for environments

Summary

adds information on how to use and create environments

Checklist

• I have added tests to cover my changes (if necessary)
• I have updated documentation (if necessary)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.52%. Comparing base (b0a9552) to head (f6d6548).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #837      +/-   ##
==========================================
- Coverage   88.53%   88.52%   -0.01%     
==========================================
  Files          86       86              
  Lines       17988    17988              
  Branches     3509     3509              
==========================================
- Hits        15925    15924       -1     
+ Misses       1684     1683       -1     
- Partials      379      381       +2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[tclose]

Looks great thanks!

[satra]

@tclose - this unfortunately has all kinds of errors that should be fixed. i'll open another PR. and this makes me think that we need a better of model of code testing in the docs.

also i realize that there is no example in the tests of running a python function inside a container. all the current examples are shell commands.

[tclose]

sorry, I should have checked more closely

[tclose]

This might do the trick https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html

[satra]

@tclose - if you have time to fix this up that would be great. if not, i'll have to punt this fix till friday.