The 'Quick Start' experience is a bit cryptic. Among the documentation, the help message, and the code, none clarifies what this is doing, what to expect, or what to do next.
As-run:
curl bootstrap.f0cal.com/master | python3 - --help
Problems:
- There is not a clear division between the download and the help content.
- It is not clear what application or workflow this help is for.
- It is not obvious what the bootstrap is supposed to accomplish when run without
--help.
- It is not obvious how to run bootstrap without the
--help option.
- It is not clear what to do after the bootstrap install, such as how to start the f0cal CLI.
Suggested changes (for --help):
- Add a header, including leading whitespace to separate it from the curl download output.
- Add an introduction. Explain that this is the f0cal bootstrap script to set up f0cal tools on the local computer. Explain that when run without the
--help option, it will install the f0cal tools within a new directory f0cal within the current directory, (actions related to new or existing virtual environment, or lack thereof, TBD... see other issues), then install system packages.
- Add a usage example.
For example:
(whitespace)
********************
* Welcome to f0cal *
********************
When run without the --help flag, this bootstrap script will perform the following actions:
1. Download and install f0cal tools within a new directory ./f0cal/.
2. (actions related to new or existing virtual environment, or lack thereof)
3. Install system packages such as compilers, unless run with --skip-system-packages.
Usage:
- [-h] [-d] [-v VENV_DIR] [--no-sudo] [--skip-system-packages] {git,local,pip}
positional arguments:
{git,local,pip}
git Install from GitHub
optional arguments:
-h, --help Show this help message and exit
-d, --debug Enable debug logging
-v VENV_DIR, --venv-dir VENV_DIR
Directory at which to create python virtual environment
--no-sudo Install without sudo
--skip-system-packages
Do not install system wide packages such as compilers
Usage example:
curl bootstrap.f0cal.com/master | python3 - -v f0cal/venv git
# Install from GitHub, using a new virtual environment for python packages, and include system wide packages.
After bootstrap installation, continue with instructions in f0cal/README.md.
The 'Quick Start' experience is a bit cryptic. Among the documentation, the help message, and the code, none clarifies what this is doing, what to expect, or what to do next.
As-run:
curl bootstrap.f0cal.com/master | python3 - --helpProblems:
--help.--helpoption.Suggested changes (for
--help):--helpoption, it will install the f0cal tools within a new directoryf0calwithin the current directory, (actions related to new or existing virtual environment, or lack thereof, TBD... see other issues), then install system packages.For example: