Browse Source

update the ReadMe file and add screenshots.

master
Craig Oates 4 years ago
parent
commit
9f9bee6147
  1. 92
      README.md
  2. BIN
      media/cli-example-1.png
  3. BIN
      media/cli-example-2.png
  4. BIN
      media/cli-example-3.png

92
README.md

@ -1,3 +1,91 @@
# shortcut-learner # Shortcut Learner
This is a Python 3 console program which displays a personal collection of shortcuts. It, also, has a feature to append new shortcuts to your collection via the Command Line Interface (C.L.I.). or manually editing the shortcuts file (a markdown file).
The rendering is done mostly with a Python package called *Rich*: A library for rich text formatting in the terminal. In this instance, *Shortcut Learner* is using the Markdown rendering feature most of all. For more information on *Rich*, please use the following link: [https://github.com/willmcgugan/rich](Rich's Repository).
## Pre-Requisites
To use *Shortcut Learner*, I recommend you meet the following:
- You have experience with [Python3](https://www.python.org/).
- You can create a [virtual environment](https://realpython.com/python-virtual-environments-a-primer/) in Python.
- You know how to install packages with [Pip](https://pip.pypa.io/en/stable/) -- via "requirements.txt".
- Comfortable with Linux -- This is not tested on MacOS or Windows.
- Comfortable using a terminal and [Bash](https://www.gnu.org/software/bash/).
- **(Optional Extra)** Comfortable creating a Python binary using [PyInstaller](https://www.pyinstaller.org/).
- **(Optional Extra)** Familiar with [Rich](https://github.com/willmcgugan/rich) (Python library).
## Quick Start
I assume you are wanting to use this from within a Python virtual environment. If you do not, install the packages from *requirements.txt* without creating a virtual environment (I.E. ignore steps 1 and 2). Also, make sure you have cloned the repository and you are in its directory.
```bash
# 1. Create a virtual environment.
python3 -m venv venv
# 2. Activate the virtual environment.
. venv/bin/activate # Replace . with source if that's your preference.
# 3. Install the packages.
pip install -r requirements.txt
# 4. Run the script.
python scl.py
```
Assuming this is the first time you have used this script, it will show you a message saying it cannot find your shortcuts file. If that is true, it will provide an option to create one for you. The default is `y` (yes). The name of the file the program creates is *shortcut-learner.md* and stores it your *home* directory.
To add a shortcut to your list, (assuming you are still in the project's working directory) use `python scl.py -a "[Enter your shortcut here]"`.
## Shortcut-Learner.md: The Programs Data File
Because the program stores your shortcuts in a markdown file, you can edit the file manually if you prefer. The reason for this design decision is it allows you to keep it open as working file which you can add to throughout the day. With that said, opening the file in a text editor can sometimes feel like a excessive amount of memory usage (in proportion to the features provided) or you might prefer working inside a C.L.I. So, doing it this way, allows you to use it how you like. In other words, VS Code or C.L.I.? Either way is fine.
## Screenshots
![CLI Example](./media/cli-example-1.png)
![CLI Example](./media/cli-example-2.png)
![CLI Example](./media/cli-example-3.png)
## Tips/Ideas
### Create Binary
With the listed packages, you will find *PyInstaller*. If you want to use this without the need to touch the source code, you can create a binary and run *Shortcut Learner* from that. The easiest way to create the binary is to run (whilst in the project's directory) either of the following commands:
```bash
# This command creates a binary as a one file.
python pyinstaller --onefile scl.py
# This command creates a binary with folders.
python pyinstaller scl.py
```
If you are unfamiliar with *PyInstaller*, you can read an introductory overview at [pypi.org](https://pypi.org/project/PyInstaller/).
### Access Shortcut Learner Across Your System (via the Terminal)
One of the main points for making *Shortcut Learner* was to have access to your shortcut list as quickly as possible. One of the quickest ways to access something is, usually, through your terminal via *(insert your "Bash" preference here)*. With that said, navigating to the script or the binary (see section above) and then running it can be combersome. One way to get around that is to add it to your `Path`. The easiest way to do that is to create a (one file) binary and copy it to your */usr/bin/* directory. If you are in the project's root directory and your have created a binary (see section above), enter `sudo cp dist/scl/usr/bin`. After that, you can access *Shortcut Learner* by entering `scl` into your terminal. If you want to remove it, enter `sudo rm /usr/bin/scl` **Becareful executing this command**.
### Create Global Shortcut to Append and Open Shortcut Learner
For *Shortcut Learner* to work (for me), it needs to be as accessible as a glance and inputting data needs to feel as close to writing a Post-It note and sticking it to your monitor as possible. To achieve this, I have created two global shortcuts. One to add a shortcut to the list (via a new terminal prompt) and another to show the shortcuts in a new separate terminal.
**This was done using KDE's Plama desktop so your mileage might vary.** I have, also, sacrificed my num-pad (or 17 free customise-able buttons as I like to call them) and use the buttons as "shortcut buttons". Again, this means your mileage might vary.
### Create Custom Profiles in Your Terminal and Utilise the Formatting in the Programs Output.
Because *Shortcut Learner* uses *Rich* to render your collection of shortcuts, you can create a profile in your terminal to make it easier to read/scan/prioritise certain points/Etc. Use the screenshots above as a starting-point.
### Pick a Style of Writing Which Suits You
Your collection of shortcuts are personal to you. So, pick a format (in markdown) which makes sense to you. If you want section headers and bullet-point lists, do that. If you prefer one giant numbered-list, do that. You can, also, just have paragraphs if you want. Feel free to use markdown's code/syntax highlighting if that helps. Personally, I like a numbered-list with the shortcut highlighted with the `code/syntax` highlighter followed by a quick description of what it does and the program it is used in. See the screenshots above for an example of this.
### Jump Between Editing Your Shortcut File Manually and The Programs Append Feature
Because the file used to store your collection of shortcuts is a markdown file (called *shortcut-learner.md*), you can edit it like any other text file. I recommend adding quick one-line shortcuts with `scl -a "[Enter shortcut here]"` and more detailed entries via your text editor. You can find this file at `~/shortcut-learner.md`.
A python base console program which displays a personal collection of shortcuts.

BIN
media/cli-example-1.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 99 KiB

BIN
media/cli-example-2.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 140 KiB

BIN
media/cli-example-3.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.1 MiB

Loading…
Cancel
Save