From 5354948ae653888a190b5d45ea4f787510807d34 Mon Sep 17 00:00:00 2001 From: Whisperity Date: Sun, 29 May 2022 11:45:58 +0200 Subject: [PATCH] chore: Cleanup old README, PyPI install, and fix documentation --- README.md | 94 ++++++---------------------------- RELEASE_NOTES.md | 39 -------------- docs/install.rst | 24 ++++++++- docs/reference/environment.rst | 2 +- setup.py | 4 +- 5 files changed, 43 insertions(+), 120 deletions(-) delete mode 100644 RELEASE_NOTES.md diff --git a/README.md b/README.md index 8ac1b85..06411d6 100644 --- a/README.md +++ b/README.md @@ -41,9 +41,18 @@ These are the configurations that the [CI](http://github.com/whisperity/Envprobe ### Download -You can grab Envprobe from the GitHub repository, either via `git` or in a tarball form. -Download the project anywhere you please. -In this example, we'll use `~/envprobe`. +You can download Envprobe's official releases from [PyPI](http://pypi.org/project/envprobe). + +~~~{.sh} +pip install envprobe +~~~ + + +#### From GitHub + +You can also download Envprobe from the GitHub repository, either via `git` or in a tarball form. +Download the project anywhere you please, and extract the archive. +In this example, we'll use `~/envprobe` as the location. ~~~{.sh} git clone http://github.com/whisperity/envprobe.git ~/envprobe \ @@ -68,11 +77,11 @@ The easiest way to do this is to add the hook script at the end of the configura > **:warning: Note!** If you are using other custom shell extensions, it is **well-advised** for the best experience to load Envprobe **last**. -| Shell | Configuration file (usually) | Code to add | -|:-----------------------------------|:-----------------------------------------------------:|:----------------------------------------------------:| -| Bash | `~/.bashrc` | `eval "$(~/envprobe/envprobe config hook bash $$)";` | -| Zsh (stock) | `~/.zshrc` | `eval "$(~/envprobe/envprobe config hook zsh $$)";` | -| Zsh ([Oh My Zsh](http://ohmyz.sh)) | `~/.oh-my-zsh/custom/zzzzzz_envprobe.zsh` (new file!) | `eval "$(~/envprobe/envprobe config hook zsh $$)";` | +| Shell | Configuration file (usually) | Code to add | +|:-----------------------------------|:-----------------------------------------------------:|:-----------------------------------------:| +| Bash | `~/.bashrc` | `eval "$(envprobe config hook bash $$)";` | +| Zsh (stock) | `~/.zshrc` | `eval "$(envprobe config hook zsh $$)";` | +| Zsh ([Oh My Zsh](http://ohmyz.sh)) | `~/.oh-my-zsh/custom/zzzzzz_envprobe.zsh` (new file!) | `eval "$(envprobe config hook zsh $$)";` | ## Quick user guide @@ -268,72 +277,3 @@ The description of a variable, when queried, may come from a local copy of this To initially download, or subsequently update, the description database, execute: epc descriptions update - - ---- - ---- - -# :warning: OLD DOCUMENTATION - -> :loudspeaker: Below follows the documentation for the **previous version** of Envprobe that is being rewritten. -> Some of the parts might no longer or not yet apply! - -Why? ----- - -However, there is a use case on which all of the aforementioned tools fall -short, or are hard to configure. **`envprobe`** — the name idea came -from [`modprobe`](http://enwp.org/Modprobe), but for environments — -was born out of this personal necessity, to give the ability to easily -configure your shell, without the need of actually writing tedious -configuration files, to either of these mentioned systems. - - - -How to Install? ---------------- - - -### Invoking *Envprobe* - -After envprobe is installed, you can use it in the shell with the `envprobe` -or `ep` command. **You should NOT alter `PATH` or use the absolute -`~/envprobe/envprobe.py` path to access `envprobe`.** The hook executed by -the lines above enabled `envprobe` for you. - - - -Advanced: Configuring type of variables ---------------------------------------- - - * `ignored`: Remove the variable from Envprobe's allowed and managed - variables. - -*Note:* Setting a variable's *type* to `ignored` is not the same as -*"tracking ignoring"* a variable. "Tracking ignore" means that changes of the -variable is not visible to the `diff`, `save`, `load`, ... commands, but -the variable can still be managed locally, in an ad-hoc fashion. A variable -with `ignored` type will result in Envprobe rejecting every access (`get`, -`set`) on that variable. - - - -Extreme: Resetting or hacking *Envprobe* ----------------------------------------- - -We share the philosophy of small individual commands and easily readable -configuration files in this project. Your local configuration is saved under -`~/.local/share/envprobe` in the form of JSON files. Adventurous and power -users are welcome to tinker their configuration through these files, but be -advised that we cannot provide any help in case a mess-up happens. - -To make Envprobe *completely **and irrevocably** forget* all configuration, -along with **all your saved states!**, simply delete the aforementioned folder, -and then restart your Terminal. - -**Warning!** Data and configuration specific to a running shell session is -saved to a temporary folder and might include binary files and files with -ephemeral lifespan. These files are not meant to be altered manually apart -from development or debugging purposes. Altering these files can make your -running shell irrevocably broken! diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md deleted file mode 100644 index 9d7ad8a..0000000 --- a/RELEASE_NOTES.md +++ /dev/null @@ -1,39 +0,0 @@ -Release notes for Envprobe `v1.0` -================================= - -> :bulb: **Note!** Normally, the commit history between two releases should suffice as the release notes, but this major rewrite is so huge we need this extra bit to keep track. - -New features and enhancements :newspaper: ------------------------------------------ - - * There's a shorter and more concise [README](/README.md), and a better and longer full [Documentation](/docs/index.rst) available. - * *Envprobe* is now designed with offering most of the low-level functionality as a Python library, with the user-facing commands simply bolted on top. - The internal details have been highly refactored and better documented. - * There is now an automated CI system and testing! (#8) - * Envprobe will now use the most temporary location possible to store the temporary files needed for operation, and will try its best to clean up after itself. (#11) - - -Bug fixes and performance improvements :beetle: ------------------------------------------------ - - * Fixed an issue with invalid control code generation when a variable's value contained spaces (#12). - * Fixed saving changes to a PATH-like variable and then saving some more changes to it destroying the original saved values (#2). - * Fixed the issue with saving or loading a snapshot resulted in the entire environment considered "stamped" (i.e. no more diffs between the current state and the known state), as opposed to only the changes that affected the variables actually saved or loaded. (#14) - * Improved the handling of the control file to be done in Python, breaking our reliance on `/bin/cat` and `/bin/rm` (i.e. `/bin` being in `PATH`) being available. (#15) - - -Backwards incompatible and other game-breaking changes :warning: ----------------------------------------------------------------- - - * The `envprobe.py` and `envprobe-config.py` entry point scripts have been **removed** and the shell hook made shorter and simpler. (#10) - Now, the `envprobe` is the **only** entry point through which the program can be called. - * The `epc track` and `epc default-tracking` commands have been merged together into the `epc track` command. - Setting the *default behaviour* (previously through `epc default-tracking`) is done by giving the `--default` flag. - Resetting a particular variable's behaviour to the default (previously done by `epc track --default`) is done by using `epc track --reset`. - * The `epc set-type` and `epc set-description` commands have been merged together into the `epc set` command. - The individual properties of the variable to be set can be specified with `--type` and `--description`, respectively. - * The `epc update-community` command was moved to `epc descriptions update`. - The format of the datafiles were changed for clarity, and are backwards incompatible. - * Envprobe's user-level configuration files have been moved to `~/.config/envprobe` by default. - * The internals of the implementation have been almost completely reworked, which means everything that relied upon Envprobe on the Python scripting level is surely broken! - * The format of the user configuration files have changed in an incompatible way, too. diff --git a/docs/install.rst b/docs/install.rst index fe29214..69ccd25 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -10,8 +10,18 @@ Apart from Python and one of the supported POSIX-compatible shells, there are no Obtaining Envprobe ================== +You can download Envprobe's official releases from `PyPI `_. +``pip`` will automatically install *Envprobe* to an appropriate location for your local user. + +.. code-block:: bash + + pip install envprobe + + +From GitHub +----------- You can download Envprobe from the `official repository `_, either using `Git `_ or a ``tar`` download. -Extract the downloaded files to any location comfortable. +Extract the downloaded archive to any location comfortable. In the documentation, we will use ``~/envprobe`` as the location where Envprobe is installed to. .. code-block:: bash @@ -50,6 +60,10 @@ Put the following code as-is (including quotes, etc.) at the end of ``~/.bashrc` .. code-block:: bash + # If obtained from PyPI: + eval "$(envprobe config hook bash $$)"; + + # If obtained from GitHub: eval "$(~/envprobe/envprobe config hook bash $$)"; Zsh @@ -62,6 +76,10 @@ Put the following code as-is (including quotes, etc.) at the end of ``~/.zshrc`` .. code-block:: bash + # If obtained from PyPI: + eval "$(envprobe config hook zsh $$)"; + + # If obtained from GitHub: eval "$(~/envprobe/envprobe config hook zsh $$)"; @@ -72,6 +90,10 @@ If you are using `Oh-My-Zsh `_ to manage your Zsh, create a new .. code-block:: bash + # If obtained from PyPI: + eval "$(envprobe config hook zsh $$)"; + + # If obtained from GitHub: eval "$(~/envprobe/envprobe config hook zsh $$)"; diff --git a/docs/reference/environment.rst b/docs/reference/environment.rst index 0b6f0c5..ba5f6c4 100644 --- a/docs/reference/environment.rst +++ b/docs/reference/environment.rst @@ -67,6 +67,6 @@ All these classes are subclasses of :py:class:`EnvVarTypeHeuristic