Skip to content

Improve Bootstrap 'Quick Start' help output and/or documentation #3

Description

@JeffreyUrban

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions