From 71a2e2f600b14856435699c35ff1fa9bf95e24b0 Mon Sep 17 00:00:00 2001 From: Daylin Morgan Date: Thu, 3 Aug 2023 18:17:23 -0500 Subject: [PATCH] docs: update svgs --- docs/index.md | 130 -------------------------- docs/svgs/viv-exe-help.svg | 72 +++++++------- docs/svgs/viv-exe-pip-help.svg | 72 +++++++------- docs/svgs/viv-exe-python-help.svg | 72 +++++++------- docs/svgs/viv-freeze-help.svg | 70 +++++++------- docs/svgs/viv-help.svg | 108 +++++++++++---------- docs/svgs/viv-manage-install-help.svg | 54 ++++++----- docs/svgs/viv-manage-purge-help.svg | 54 ++++++----- docs/svgs/viv-manage-update-help.svg | 54 ++++++----- docs/svgs/viv-run-help.svg | 98 ++++++++++--------- docs/svgs/viv-shim-help.svg | 102 ++++++++++---------- scripts/generate-svgs.py | 2 + 12 files changed, 390 insertions(+), 498 deletions(-) delete mode 100644 docs/index.md mode change 100644 => 100755 scripts/generate-svgs.py diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 52a0a25..0000000 --- a/docs/index.md +++ /dev/null @@ -1,130 +0,0 @@ -# viv - -
- - Logo - -

- viv isn't venv -

-

- Documentation -

-
- -Try before you buy! -```sh -python3 <(curl -fsSL viv.dayl.in/viv.py) run pycowsay -- "viv isn't venv\!" -``` ---- - -`Viv` is a standalone dependency-free `venv` creator. - -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 also remove your user site directory. -(view with: `python -m 'import site;print(site.USER_SITE)'`). - -`Viv`'s uncompromising insistence on portability means that it will always (1) only use the standard library (2) never exceed a single script. - -For that reason any usage of the `CLI` can be accomplished using a remote copy as seen in the below install command. - -## Setup - -Run the below command to install `viv`. - -```sh -python3 <(curl -fsSL viv.dayl.in/viv.py) manage install -``` - -To access `viv` from within scripts you should add it's location to your `PYTHONPATH`. -By default `viv` will be installed to `$XDG_DATA_HOME/viv` or `~/.local/share/viv` you can customize this with `--src`. - -```sh -export PYTHONPATH="$PYTHONPATH:$HOME/.local/share/viv" -``` - -Advanced users may recognize that principally, -the module just needs to be recognized at run time -and the single script [`viv.py`](https://github.com/daylinmorgan/viv/blob/main/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 - -In any python script with external dependencies you can add this line, -to automate `vivenv` creation and installation of dependencies. - -```python -__import__("viv").use("click") -``` - -To remove all `vivenvs` you can use the below command: - -```sh -viv remove $(viv list -q) -``` - -To remove `viv` all together you can use the included `purge` command: - -```sh -python3 <(curl -fsSL viv.dayl.in/viv.py) manage purge -``` - -## Additional Features - -An experimental feature of `viv` is generating shim's that leverage the principles of `viv`. -These shims would operate similar to `pipx` in which you can specify a command line app to "install". - -*Note* that `--standalone` will auto-generate a code-golfed minified version of `viv` to accomplish the same basic task as using a local copy of `viv`. -After generating this a standalone `shim` you can freely use this script across unix machines which have `python>3.8`. -See [examples/black](https://github.com/daylinmorgan/viv/blob/dev/examples/black) for output of below command. - -```sh -python3 <(curl -fsSL viv.dayl.in/viv.py) shim black -o ./black --standalone --freeze -``` - -## Alternatives - -### [pip-run](https://github.com/jaraco/pip-run) - -```sh -pip-run (10.0.5) -├── autocommand (2.2.2) -├── jaraco-context (4.3.0) -├── jaraco-functools (3.6.0) -│ └── more-itertools (9.1.0) -├── jaraco-text (3.11.1) -│ ├── autocommand (2.2.2) -│ ├── inflect (6.0.2) -│ │ └── pydantic>=1.9.1 (1.10.5) -│ │ └── typing-extensions>=4.2.0 (4.5.0) -│ ├── jaraco-context>=4.1 (4.3.0) -│ ├── jaraco-functools (3.6.0) -│ │ └── more-itertools (9.1.0) -│ └── more-itertools (9.1.0) -├── more-itertools>=8.3 (9.1.0) -├── packaging (23.0) -├── path>=15.1 (16.6.0) -├── pip>=19.3 (23.0.1) -└── platformdirs (3.1.0) -``` - -### [pipx](https://github.com/pypa/pipx/) - -```sh -pipx (1.1.0) -├── argcomplete>=1.9.4 (2.1.1) -├── packaging>=20.0 (23.0) -└── userpath>=1.6.0 (1.8.0) - └── click (8.1.3) -``` diff --git a/docs/svgs/viv-exe-help.svg b/docs/svgs/viv-exe-help.svg index 5d16aa5..cbf6eaf 100644 --- a/docs/svgs/viv-exe-help.svg +++ b/docs/svgs/viv-exe-help.svg @@ -19,14 +19,14 @@ font-weight: 700; } - .terminal-2174466350-matrix { + .terminal-3409362442-matrix { font-family: Fira Code, monospace; font-size: 20px; line-height: 24.4px; font-variant-east-asian: full-width; } - .terminal-2174466350-title { + .terminal-3409362442-title { font-size: 18px; font-weight: bold; font-family: arial; @@ -36,80 +36,80 @@ -webkit-filter: drop-shadow( 2px 5px 2px rgba(0, 0, 0, .7)); filter: drop-shadow( 2px 5px 2px rgba(0, 0, 0, .7)); } - .terminal-2174466350-r1 { fill: #94e2d5;font-weight: bold } -.terminal-2174466350-r2 { fill: #c6d0f5 } -.terminal-2174466350-r3 { fill: #f9e2af;font-weight: bold } + .terminal-3409362442-r1 { fill: #94e2d5;font-weight: bold } +.terminal-3409362442-r2 { fill: #c6d0f5 } +.terminal-3409362442-r3 { fill: #f9e2af;font-weight: bold } - + - + - + - + - + - + - + - + - + - + - + - + - + - + - viv exe --help + viv exe --help - + - - usage: viv exe [-h] vivenv cmd - -run binary/script in existing vivenv - -examples: -    viv exe <vivenv> pip -- list -    viv exe <vivenv> python -- script.py - -positional arguments: -vivenv        name/hash of vivenv -cmd           command to to execute - -options: --h, --help    show this help message and exit + + usage: viv exe [-h] vivenv cmd + +run binary/script in existing vivenv + +examples: +    viv exe <vivenv> python -- script.py +    viv exe <vivenv> python -- -m http.server + +positional arguments: +vivenv        name/hash of vivenv +cmd           command to to execute + +options: +-h, --help    show this help message and exit diff --git a/docs/svgs/viv-exe-pip-help.svg b/docs/svgs/viv-exe-pip-help.svg index 2f3721d..7c99d23 100644 --- a/docs/svgs/viv-exe-pip-help.svg +++ b/docs/svgs/viv-exe-pip-help.svg @@ -19,14 +19,14 @@ font-weight: 700; } - .terminal-1793440407-matrix { + .terminal-3354443635-matrix { font-family: Fira Code, monospace; font-size: 20px; line-height: 24.4px; font-variant-east-asian: full-width; } - .terminal-1793440407-title { + .terminal-3354443635-title { font-size: 18px; font-weight: bold; font-family: arial; @@ -36,80 +36,80 @@ -webkit-filter: drop-shadow( 2px 5px 2px rgba(0, 0, 0, .7)); filter: drop-shadow( 2px 5px 2px rgba(0, 0, 0, .7)); } - .terminal-1793440407-r1 { fill: #94e2d5;font-weight: bold } -.terminal-1793440407-r2 { fill: #c6d0f5 } -.terminal-1793440407-r3 { fill: #f9e2af;font-weight: bold } + .terminal-3354443635-r1 { fill: #94e2d5;font-weight: bold } +.terminal-3354443635-r2 { fill: #c6d0f5 } +.terminal-3354443635-r3 { fill: #f9e2af;font-weight: bold } - + - + - + - + - + - + - + - + - + - + - + - + - + - + - viv exe pip --help + viv exe pip --help - + - - usage: viv exe [-h] vivenv cmd - -run binary/script in existing vivenv - -examples: -    viv exe <vivenv> pip -- list -    viv exe <vivenv> python -- script.py - -positional arguments: -vivenv        name/hash of vivenv -cmd           command to to execute - -options: --h, --help    show this help message and exit + + usage: viv exe [-h] vivenv cmd + +run binary/script in existing vivenv + +examples: +    viv exe <vivenv> python -- script.py +    viv exe <vivenv> python -- -m http.server + +positional arguments: +vivenv        name/hash of vivenv +cmd           command to to execute + +options: +-h, --help    show this help message and exit diff --git a/docs/svgs/viv-exe-python-help.svg b/docs/svgs/viv-exe-python-help.svg index f81638f..b8ffb80 100644 --- a/docs/svgs/viv-exe-python-help.svg +++ b/docs/svgs/viv-exe-python-help.svg @@ -19,14 +19,14 @@ font-weight: 700; } - .terminal-2696068080-matrix { + .terminal-207667404-matrix { font-family: Fira Code, monospace; font-size: 20px; line-height: 24.4px; font-variant-east-asian: full-width; } - .terminal-2696068080-title { + .terminal-207667404-title { font-size: 18px; font-weight: bold; font-family: arial; @@ -36,80 +36,80 @@ -webkit-filter: drop-shadow( 2px 5px 2px rgba(0, 0, 0, .7)); filter: drop-shadow( 2px 5px 2px rgba(0, 0, 0, .7)); } - .terminal-2696068080-r1 { fill: #94e2d5;font-weight: bold } -.terminal-2696068080-r2 { fill: #c6d0f5 } -.terminal-2696068080-r3 { fill: #f9e2af;font-weight: bold } + .terminal-207667404-r1 { fill: #94e2d5;font-weight: bold } +.terminal-207667404-r2 { fill: #c6d0f5 } +.terminal-207667404-r3 { fill: #f9e2af;font-weight: bold } - + - + - + - + - + - + - + - + - + - + - + - + - + - + - viv exe python --help + viv exe python --help - + - - usage: viv exe [-h] vivenv cmd - -run binary/script in existing vivenv - -examples: -    viv exe <vivenv> pip -- list -    viv exe <vivenv> python -- script.py - -positional arguments: -vivenv        name/hash of vivenv -cmd           command to to execute - -options: --h, --help    show this help message and exit + + usage: viv exe [-h] vivenv cmd + +run binary/script in existing vivenv + +examples: +    viv exe <vivenv> python -- script.py +    viv exe <vivenv> python -- -m http.server + +positional arguments: +vivenv        name/hash of vivenv +cmd           command to to execute + +options: +-h, --help    show this help message and exit diff --git a/docs/svgs/viv-freeze-help.svg b/docs/svgs/viv-freeze-help.svg index f9d0949..f15f337 100644 --- a/docs/svgs/viv-freeze-help.svg +++ b/docs/svgs/viv-freeze-help.svg @@ -19,14 +19,14 @@ font-weight: 700; } - .terminal-3188460144-matrix { + .terminal-1818495600-matrix { font-family: Fira Code, monospace; font-size: 20px; line-height: 24.4px; font-variant-east-asian: full-width; } - .terminal-3188460144-title { + .terminal-1818495600-title { font-size: 18px; font-weight: bold; font-family: arial; @@ -36,77 +36,77 @@ -webkit-filter: drop-shadow( 2px 5px 2px rgba(0, 0, 0, .7)); filter: drop-shadow( 2px 5px 2px rgba(0, 0, 0, .7)); } - .terminal-3188460144-r1 { fill: #94e2d5;font-weight: bold } -.terminal-3188460144-r2 { fill: #c6d0f5 } -.terminal-3188460144-r3 { fill: #f9e2af;font-weight: bold } -.terminal-3188460144-r4 { fill: #f9e2af } + .terminal-1818495600-r1 { fill: #94e2d5;font-weight: bold } +.terminal-1818495600-r2 { fill: #c6d0f5 } +.terminal-1818495600-r3 { fill: #f9e2af;font-weight: bold } +.terminal-1818495600-r4 { fill: #f9e2af } - + - + - + - + - + - + - + - + - + - + - + - + - + - viv freeze --help + viv freeze --help - + - - usage: viv freeze [-h] [-p {abs,rel}] [-s] [-k] [-r <path>] [reqs ...] - -create import statement from package spec - -positional arguments: -reqs                         requirements specifiers - -options: --h, --help                   show this help message and exit --p, --path {abs,rel}         generate line to add viv to sys.path --s, --standalone             generate standalone activation function --k, --keep                   preserve environment --r, --requirements <path>    path/to/requirements.txt file + + usage: viv freeze [-h] [-p {abs,rel}] [-s] [-r <path>] [-k] [reqs ...] + +create import statement from package spec + +positional arguments: +reqs                         requirements specifiers + +options: +-h, --help                   show this help message and exit +-p, --path {abs,rel}         generate line to add viv to sys.path +-s, --standalone             generate standalone activation function +-r, --requirements <path>    path/to/requirements.txt file +-k, --keep                   preserve environment diff --git a/docs/svgs/viv-help.svg b/docs/svgs/viv-help.svg index 8a22a00..be33cdd 100644 --- a/docs/svgs/viv-help.svg +++ b/docs/svgs/viv-help.svg @@ -1,4 +1,4 @@ - + - - + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - - - - viv  --help + viv  --help - + - - usage: viv [-h] [-V] <sub-cmd> ... - -vivisn'tvenv! -to create/activate a vivenv: -- from command line: `viv -h` -- within python script: __import__("viv").use("typer", "rich-click") - -options: --h, --help       show this help message and exit --V, --version    show program's version number and exit - -subcommands: -<sub-cmd> -list (l)       list all vivenvs -shim (s)       generate viv-powered cli apps -run (r)        run an app with an on-demand venv -exe (e)        run binary/script in existing vivenv -remove (rm)    remove a vivenv -freeze (f)     create import statement from package spec -info (i)       get metadata about a vivenv -manage (m)     manage viv itself + + usage: viv [-h] [-V] <sub-cmd> ... + +vivisn'tvenv +command line: `viv --help` +python api: __import__("viv").use("typer", "rich-click") + +options: +-h, --help       show this help message and exit +-V, --version    show program's version number and exit + +subcommands: +<sub-cmd> +list (l)       list all vivenvs +shim (s)       generate viv-powered cli apps +run (r)        run an app/script with an on-demand venv +exe (e)        run binary/script in existing vivenv +remove (rm)    remove a vivenv +freeze (f)     create import statement from package spec +info (i)       get metadata about a vivenv +manage (m)     manage viv itself diff --git a/docs/svgs/viv-manage-install-help.svg b/docs/svgs/viv-manage-install-help.svg index 734bdb0..cac72ac 100644 --- a/docs/svgs/viv-manage-install-help.svg +++ b/docs/svgs/viv-manage-install-help.svg @@ -1,4 +1,4 @@ - + - - + + - + - + - + - + - + - + + + + - viv manage install --help + viv manage install --help - + - - usage: viv manage install [-h] [-r <ref>] [-s <src>] [-c <cli>] - -options: --h, --help         show this help message and exit --r, --ref <ref>    git reference (branch/tag/commit) --s, --src <src>    path/to/source_file --c, --cli <cli>    path/to/cli (symlink to src) + + usage: viv manage install [-h] [-r <ref>] [-s <src>] [-c <cli>] [-y] + +options: +-h, --help         show this help message and exit +-r, --ref <ref>    git reference (branch/tag/commit) +-s, --src <src>    path/to/source_file +-c, --cli <cli>    path/to/cli (symlink to src) +-y, --yes          respond yes to all prompts diff --git a/docs/svgs/viv-manage-purge-help.svg b/docs/svgs/viv-manage-purge-help.svg index e230ae4..1ec3ae0 100644 --- a/docs/svgs/viv-manage-purge-help.svg +++ b/docs/svgs/viv-manage-purge-help.svg @@ -1,4 +1,4 @@ - + - - + + - + - + - + - + - + - + + + + - viv manage purge --help + viv manage purge --help - + - - usage: viv manage purge [-h] [-r <ref>] [-s <src>] [-c <cli>] - -options: --h, --help         show this help message and exit --r, --ref <ref>    git reference (branch/tag/commit) --s, --src <src>    path/to/source_file --c, --cli <cli>    path/to/cli (symlink to src) + + usage: viv manage purge [-h] [-r <ref>] [-s <src>] [-c <cli>] [-y] + +options: +-h, --help         show this help message and exit +-r, --ref <ref>    git reference (branch/tag/commit) +-s, --src <src>    path/to/source_file +-c, --cli <cli>    path/to/cli (symlink to src) +-y, --yes          respond yes to all prompts diff --git a/docs/svgs/viv-manage-update-help.svg b/docs/svgs/viv-manage-update-help.svg index becad89..cf51137 100644 --- a/docs/svgs/viv-manage-update-help.svg +++ b/docs/svgs/viv-manage-update-help.svg @@ -1,4 +1,4 @@ - + - - + + - + - + - + - + - + - + + + + - viv manage update --help + viv manage update --help - + - - usage: viv manage update [-h] [-r <ref>] [-s <src>] [-c <cli>] - -options: --h, --help         show this help message and exit --r, --ref <ref>    git reference (branch/tag/commit) --s, --src <src>    path/to/source_file --c, --cli <cli>    path/to/cli (symlink to src) + + usage: viv manage update [-h] [-r <ref>] [-s <src>] [-c <cli>] [-y] + +options: +-h, --help         show this help message and exit +-r, --ref <ref>    git reference (branch/tag/commit) +-s, --src <src>    path/to/source_file +-c, --cli <cli>    path/to/cli (symlink to src) +-y, --yes          respond yes to all prompts diff --git a/docs/svgs/viv-run-help.svg b/docs/svgs/viv-run-help.svg index 99aab0a..9cddecd 100644 --- a/docs/svgs/viv-run-help.svg +++ b/docs/svgs/viv-run-help.svg @@ -1,4 +1,4 @@ - + - - + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + + + + + + - viv run --help + viv run --help - + - - usage: viv run [-h] [-k] [-r <path>] [-b <bin>] [reqs ...] - -run an app with an on-demand venv - -examples: -  viv r pycowsay -- "viv isn't venv\!" -  viv r rich -b python -- -m rich - -positional arguments: -reqs                         requirements specifiers - -options: --h, --help                   show this help message and exit --k, --keep                   preserve environment --r, --requirements <path>    path/to/requirements.txt file --b, --bin <bin>              console_script/script to invoke + + usage: viv run [-h] [-s <script>] [-r <path>] [-k] [-b <bin>] [reqs  +...] + +run an app/script with an on-demand venv + +examples: +  viv r pycowsay -- "viv isn't venv\!" +  viv r rich -b python -- -m rich +  viv r -s <remote python script> + +positional arguments: +reqs                         requirements specifiers + +options: +-h, --help                   show this help message and exit +-s, --script <script>        remote script to run +-r, --requirements <path>    path/to/requirements.txt file +-k, --keep                   preserve environment +-b, --bin <bin>              console_script/script to invoke diff --git a/docs/svgs/viv-shim-help.svg b/docs/svgs/viv-shim-help.svg index ebdb9bd..0fc1117 100644 --- a/docs/svgs/viv-shim-help.svg +++ b/docs/svgs/viv-shim-help.svg @@ -19,14 +19,14 @@ font-weight: 700; } - .terminal-783195567-matrix { + .terminal-3211173715-matrix { font-family: Fira Code, monospace; font-size: 20px; line-height: 24.4px; font-variant-east-asian: full-width; } - .terminal-783195567-title { + .terminal-3211173715-title { font-size: 18px; font-weight: bold; font-family: arial; @@ -36,109 +36,109 @@ -webkit-filter: drop-shadow( 2px 5px 2px rgba(0, 0, 0, .7)); filter: drop-shadow( 2px 5px 2px rgba(0, 0, 0, .7)); } - .terminal-783195567-r1 { fill: #94e2d5;font-weight: bold } -.terminal-783195567-r2 { fill: #c6d0f5 } -.terminal-783195567-r3 { fill: #f9e2af;font-weight: bold } -.terminal-783195567-r4 { fill: #f9e2af } + .terminal-3211173715-r1 { fill: #94e2d5;font-weight: bold } +.terminal-3211173715-r2 { fill: #c6d0f5 } +.terminal-3211173715-r3 { fill: #f9e2af;font-weight: bold } +.terminal-3211173715-r4 { fill: #f9e2af } - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - viv shim --help + viv shim --help - + - - usage: viv shim [-h] [-f] [-o <path>] [-p {abs,rel}] [-s] [-k] [-r  -<path>] [-b <bin>] [reqs ...] - -generate viv-powered cli apps - -examples: -  viv shim black -  viv shim yartsu -o ~/bin/yartsu --standalone - -positional arguments: -reqs                         requirements specifiers - -options: --h, --help                   show this help message and exit --f, --freeze                 freeze/resolve all dependencies --o, --output <path>          path/to/output file --p, --path {abs,rel}         generate line to add viv to sys.path --s, --standalone             generate standalone activation function --k, --keep                   preserve environment --r, --requirements <path>    path/to/requirements.txt file --b, --bin <bin>              console_script/script to invoke + + usage: viv shim [-h] [-f] [-o <path>] [-p {abs,rel}] [-s] [-r <path>]  +[-b <bin>] [-y] [reqs ...] + +generate viv-powered cli apps + +examples: +  viv shim black +  viv shim yartsu -o ~/bin/yartsu --standalone + +positional arguments: +reqs                         requirements specifiers + +options: +-h, --help                   show this help message and exit +-f, --freeze                 freeze/resolve all dependencies +-o, --output <path>          path/to/output file +-p, --path {abs,rel}         generate line to add viv to sys.path +-s, --standalone             generate standalone activation function +-r, --requirements <path>    path/to/requirements.txt file +-b, --bin <bin>              console_script/script to invoke +-y, --yes                    respond yes to all prompts diff --git a/scripts/generate-svgs.py b/scripts/generate-svgs.py old mode 100644 new mode 100755 index 98ba3bf..11781cd --- a/scripts/generate-svgs.py +++ b/scripts/generate-svgs.py @@ -1,3 +1,5 @@ +#!/usr/bin/env python3 + from pathlib import Path from subprocess import run from textwrap import dedent