From 1dde1d0d6b1030b237207f1bd92fa9cb8ac6419f Mon Sep 17 00:00:00 2001
From: Olivier 'reivilibre <olivier@librepush.net>
Date: Sun, 24 Oct 2021 15:07:07 +0100
Subject: [PATCH] Documentation improvements

---
 docs/SUMMARY.md                           |  4 ++-
 docs/recipes/{ => environments}/docker.md |  0
 docs/recipes/environments/python.md       | 34 +++++++++++++++++++++++
 3 files changed, 37 insertions(+), 1 deletion(-)
 rename docs/recipes/{ => environments}/docker.md (100%)
 create mode 100644 docs/recipes/environments/python.md

diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index ba55c1b..e2d4eec 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -18,7 +18,9 @@
     - [Git Recipes](./recipes/filesystem/git.md)
   - [Database Recipes](./recipes/database/index.md)
     - [Postgres](./recipes/database/postgres.md)
-  - [Docker](./recipes/docker.md)
+  - [Environments](./recipes/environments/index.md)
+    - [Docker](./recipes/environments/docker.md)
+    - [Python](./recipes/environments/python.md)
 - [Resources](./resources/index.md)
   - [Filesystem Resources](./resources/filesystem.md)
 - [Utensils]()
diff --git a/docs/recipes/docker.md b/docs/recipes/environments/docker.md
similarity index 100%
rename from docs/recipes/docker.md
rename to docs/recipes/environments/docker.md
diff --git a/docs/recipes/environments/python.md b/docs/recipes/environments/python.md
new file mode 100644
index 0000000..15a3546
--- /dev/null
+++ b/docs/recipes/environments/python.md
@@ -0,0 +1,34 @@
+# Python
+
+Python is a programming language. Scone supports creating virtual Python environments to isolate dependencies.
+
+| Recipe | Needs | Provides |
+| -----: | ----- | -------- |
+| [`python-venv`](#python-venv) | `directory` | `directory` `file`? `directory`? |
+
+
+## `python-venv`
+
+Creates a Python virtual environment, installing the specified dependencies.
+
+**Provides:** `directory({dir})` and `file({dir})/bin/python`. In the future, there may be the ability to check for (and expose) other executables in the venv.
+
+| Argument | Accepted Values | Default | Description |
+| -------: | --------------- | ------- | ----------- |
+| dir | path | *required* | This is the directory to create the virtual environment in. |
+| interpreter | string or path | *required* | This specifies the desired virtual interpreter. Usually this is `python3`. |
+| install | list of requirements | *required* | This is a list of Python dependencies to install. You should specify `dir /path/to/dir` for directories, `git /path/to/dir` for local git repositories and `-r /path/to/requirements.txt` for requirements files. |
+
+`dir` and `git` requirements are currently synonymous and ensure that the venv will keep up to date using the specified directory. For now, `python-venv` is unable to cache execution if directories are in use (though this is rarely a problem). Use of the `git` keyword should be preferred for git repositories as that may allow for better performance in the future.
+
+### Example
+
+```scoml
+[[python-venv]]
+dir = "/home/abc/venv"
+interpreter = "python3"
+install:
+  - "dir /home/abc/abc"
+  - "-r /home/abc/requirements.txt"
+  - "hypercorn"
+```