From b9100ca2a16b9859508e859b0bc325101d61b42d Mon Sep 17 00:00:00 2001
From: Daylin Morgan <daylinmorgan@gmail.com>
Date: Thu, 9 Mar 2023 14:58:01 -0600
Subject: [PATCH] docs: add more full fledged documentation

---
 README.md | 40 ++++++++++++++++++++++++++++++++++------
 todo.md   |  2 ++
 2 files changed, 36 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index ea9323f..c3464da 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,22 @@
 
 See [usage](https://github.com/daylinmorgan/viv/blob/main/docs/usage.md) for more demo gifs.
 
+---
+
+Python is a great choice to quickly prototype or accomplish small tasks in scripts.
+However, leveraging it's vast ecosystem can be tedious for one-off or rarely used scripts.
+This is were `viv` comes in handy.
+
+`Viv` is a standalone dependency-free `venv` creator.
+It is meant to be invoked in any script that has third-party dependencies,
+prior to loading of any of the external modules.
+
+These `venvs` can be identified by name or by their specification.
+In any case they will be re-used across scripts (and generated on-demand, if needed).
+
+**Importantly**, `viv` will remove your user site directory (`python -m 'import site;print(site.USER_SITE)'`),
+to ensure the script isn't using anything outside the standard library and the `viv`-managed `venv`.
+
 ## Setup
 
 ### Manual (Recommended)
@@ -33,35 +49,47 @@ Place this directory on the python path in your rc file.
 export PYTHONPATH="$PYTHONPATH:$HOME/.viv/src"
 ```
 
+Advanced users may recognize that principally,
+the module just needs to be recognized at run time
+and the single script at `./src/viv/viv.py` can be invoked directly for the CLI.
+How you accomplish these options is ultimately up to you but the above instructions can get you started.
+
 ### Pypi (Not Recommended)
 
 ```sh
 pip install viv
 ```
 
+Why is this *not recommended*? Mainly, because `viv` is all about hacking your `sys.path`.
+Placing it in it's own virtual environment or installing in a user site directory may complicate this endeavor.
+
 ## Usage
 
-Then in any python script with external dependencies you can add this line,
-to automate env creation and installation of dependencies.
+In any python script with external dependencies you can add this line,
+to automate `vivenv` creation and installation of dependencies.
 
 ```python
 __import__("viv").activate("click")
 ```
 
 To remove all `vivenvs`:
+
 ```sh
 viv remove $(viv list -q)
 ```
 
-## Standalone Function
+# Standalone Viv
+
+Supposing you want to increase the portability of your script while still employing `viv`.
 
 The below function can be freely pasted at the top of your scripts and requires
-no modification of your PYTHONPATH or import of additional modules.
+no modification of your PYTHONPATH or import of additional modules (including downloading/installing `viv`).
 
-It can be auto-generated with for example: `viv freeze rich --standalone`.
+It can be auto-generated with for example: `viv freeze <spec> --standalone`.
 
-The only part necessary to modify if copied verbatim from here is the call to `_viv_activate`.
+The only part necessary to modify if copied verbatim from below is the call to `_viv_activate`.
 
+output of `viv freeze rich --standalone`:
 ```python
 # <<<<< auto-generated by daylinmorgan/viv (v.22.12a3)
 # fmt: off
diff --git a/todo.md b/todo.md
index 95a22ae..6b8911d 100644
--- a/todo.md
+++ b/todo.md
@@ -5,3 +5,5 @@
 - [ ] use config file (probably ini or toml for python>=3.11)
 - [ ] enable a garbage collection based on time or file existence (configurable)
 - [ ] unit tests (v important)
+
+- [ ] add more options to filter `viv list`