Format README and CHANGELOG

Author: connesy

CHANGELOG.md

@@ -1,17 +1,20 @@
 # Changelog
 
 ## Unreleased
+
 * The project is now following the [Github Flow](https://docs.github.com/en/get-started/using-github/github-flow) branching model. The `main` branch is now the default branch, and the `develop` branch has been removed. Future development should create a new branch directly from `main`, and when done, creating a pull request back into `main`. Releases should be tagged directly on `main` as well.
 
 ## [v2.0.0](https://github.com/SallingGroup-AI-and-ML/venv-cli/releases/tag/v2.0.0) (2024-03-06)
 
 ### Breaking changes
+
 * `venv install` can now be used to install individual packages: `venv install <package>`. [#37](https://github.com/SallingGroup-AI-and-ML/venv-cli/pull/37)
 
   To enable this feature, installing from a requirements file now requires the use of the new `-r | --requirement` flags: `venv install -r requirements.txt`. Packages installed using `venv install <package>` are first added to the requirements file before reinstalling the entire environment to ensure reproducibility. To uninstall packages, use the new `venv uninstall` subcommand, e.g. `venv uninstall <package>`.
 * `venv sync` has been removed. Use `venv install -r <requirements>.lock` instead. [#17](https://github.com/SallingGroup-AI-and-ML/venv-cli/pull/17)
 
 ### Major changes
+
 * Added `venv uninstall` subcommand to complement the new functionality of `venv install <package>`. [#37](https://github.com/SallingGroup-AI-and-ML/venv-cli/pull/37)
 
   Running `venv uninstall <package>` will first remove the package from `requirements.txt`, then use `venv install -r requirements.txt` to reinstall the environment without `<package>`.
@@ -20,17 +23,20 @@
 * Loosened the file name requirements for `requirements` files. Requirements files can now be any valid file name with the extension `.txt` (`.lock` for lock files). [#35](https://github.com/SallingGroup-AI-and-ML/venv-cli/pull/35)
 
 ### Minor changes
+
 * The `install.sh` script now supports specifying for which shell to install `venv-cli`, e.g. `./install.sh zsh`. [#29](https://github.com/SallingGroup-AI-and-ML/venv-cli/pull/29)
 * Updated virtual environment activation instructions in `README.md` and when running `venv activate -h` [#37](https://github.com/SallingGroup-AI-and-ML/venv-cli/pull/37)
 * Refactored bash completion script to enable better handling of arguments for subcommands. [8ac4daf](https://github.com/SallingGroup-AI-and-ML/venv-cli/pull/32/commits/8ac4daf89314f0ac2c1daf56bee9f4ac489f5004)
 
 ### Bug fixes
+
 * Running the uninstall script now correctly removes the sourcing line from the user's `rc`-file. [#29](https://github.com/SallingGroup-AI-and-ML/venv-cli/pull/29)
 * Running the installation script now adds the sourcing line to the user's `rc`-file only if it is not there already. [#29](https://github.com/SallingGroup-AI-and-ML/venv-cli/pull/29)
 * Running `venv <subcommand>` now correctly returns the exit code from that subcommand. [8b7a54d](https://github.com/SallingGroup-AI-and-ML/venv-cli/commit/8b7a54db77e075760847dba8c12489e7fc4dbd4d)
 * Removed a unit test that was failing sporadically when running tests multiprocessed using `pytest-xdist`. [30c501c](https://github.com/SallingGroup-AI-and-ML/venv-cli/commit/30c501ce1ef43d151ceb22718de80dc9ea9c30ac)
 
 ### Internal changes
+
 * Added several new test cases to cover loosened requirements file name check. [#35](https://github.com/SallingGroup-AI-and-ML/venv-cli/pull/35)
 * Removed unused test files. [8be87d9](https://github.com/SallingGroup-AI-and-ML/venv-cli/commit/8be87d95a75f5b532eaf1fd062796674ce7a764c)
 * Updated test cases for `venv clear` and `venv lock` that use the `venv install` command. [6985681](https://github.com/SallingGroup-AI-and-ML/venv-cli/pull/32/commits/6985681a3b3ac8ae783406e1b76401b7075ea260)
@@ -39,61 +45,74 @@
 ## [v1.5.1](https://github.com/SallingGroup-AI-and-ML/venv-cli/releases/tag/v1.5.1) (2024-01-10)
 
 ### Minor changes
+
 * `venv install` now fails early and with a more descriptve error message when run outside of a virtual environment. [#31](https://github.com/SallingGroup-AI-and-ML/venv-cli/pull/31)
 
 ### Bug fixes
+
 * `venv clear` is now able to clear virtual environments that contain editable installs. [#31](https://github.com/SallingGroup-AI-and-ML/venv-cli/pull/31)
 
 ## [v1.5.0](https://github.com/SallingGroup-AI-and-ML/venv-cli/releases/tag/v1.5.0) (2024-01-04)
 
 ### Major changes
+
 * Added `venv delete` command. [#25](https://github.com/SallingGroup-AI-and-ML/venv-cli/pull/25)
 
   Running `venv delete` completely removes the virtual environment located in the current folder.
 
 ### Minor changes
+
 * Added `-s` alias for `--skip-lock` when running `venv install`. [#24](https://github.com/SallingGroup-AI-and-ML/venv-cli/pull/24)
 
 ### Internal changes
+
 * The `run_command` test helper function can now pass through inputs to the command that is being run.
 
 ## [v1.4.1](https://github.com/SallingGroup-AI-and-ML/venv-cli/releases/tag/v1.4.1) (2023-10-30)
 
 ### Bugfixes
+
 * Fixed `venv lock` failing to lock when called as part of `venv install`. [#21](https://github.com/SallingGroup-AI-and-ML/venv-cli/pull/21)
 
 ## [v1.4.0](https://github.com/SallingGroup-AI-and-ML/venv-cli/releases/tag/v1.4.0) (2023-10-30)
 
 ### Minor changes
+
 * `venv install` now runs `venv clear` before installation. This ensures that the enrivonment doesn't end up with orphaned packages after making changes to `requirements.txt`. [#9](https://github.com/SallingGroup-AI-and-ML/venv-cli/issues/9)
 
 ## Minor changes
+
 * `venv sync` command marked as deprecated with removal planned for `v2.0`. Use `venv install <requirements>.lock` instead. [#14](https://github.com/SallingGroup-AI-and-ML/venv-cli/pull/14)
 
 ## [v1.3.0](https://github.com/SallingGroup-AI-and-ML/venv-cli/releases/tag/v1.3.0) (2023-10-30)
 
 ## Major changes
+
 * `venv lock` no longer tries to fill in credentials for packages installed via VCS. This behavior was undocumented and difficult to maintain and ultimately tried to alleviate a shortcoming of the way `pip` handles these credentials. [#11](https://github.com/SallingGroup-AI-and-ML/venv-cli/pull/11)
-For users who have credentials as part of URLs in their `requirements.txt` files, there are other ways to handle credentials, e.g. filling them in `requirements.lock` manually, using a `.netrc` file to store the credetials or using a keyring. See https://pip.pypa.io/en/stable/topics/authentication/ for more info.
+For users who have credentials as part of URLs in their `requirements.txt` files, there are other ways to handle credentials, e.g. filling them in `requirements.lock` manually, using a `.netrc` file to store the credetials or using a keyring. See [https://pip.pypa.io/en/stable/topics/authentication](https://pip.pypa.io/en/stable/topics/authentication) for more info.
 
 ### Minor changes
+
 * `venv create` now prints the full python version used for creating the environment. [bb62c21](https://github.com/SallingGroup-AI-and-ML/venv-cli/commit/bb62c216cbad2fcec06bfb1cde8b875dbfc237d3)
 
 ### Internal changes
+
 * Added `pytest-cases` to development dependencies.
 
 ## [v1.2.0](https://github.com/SallingGroup-AI-and-ML/venv-cli/releases/tag/v1.2.0) (2023-08-04)
 
 From this release forward, this project follows the `Git Flow` branching model. To reflect this, the default development branch have been renamed `develop`, and the `main` branch is now only for tagged releases.
-To read more about Git Flow, see (https://nvie.com/posts/a-successful-git-branching-model/). Also see [README](https://github.com/SallingGroup-AI-and-ML/venv-cli/blob/v1.2.0/README.md#git-flow) for branch naming conventions.
+To read more about Git Flow, see [https://nvie.com/posts/a-successful-git-branching-model](https://nvie.com/posts/a-successful-git-branching-model). Also see [README](https://github.com/SallingGroup-AI-and-ML/venv-cli/blob/v1.2.0/README.md#git-flow) for branch naming conventions.
 
 * Changed github test workflow to reflect new branch naming conventions.
 * Added better, context-based bash completions.
 
 ## [v1.1.0](https://github.com/SallingGroup-AI-and-ML/venv-cli/releases/tag/v1.1.0) (2023-08-02)
 
 ### New install script
+
 This release adds an `install.sh` script for easier installation of `venv-cli`. Now it can be installed by simply running
+
 ```console
 $ bash install.sh
 ```

README.md

@@ -1,9 +1,10 @@
 [![Linting and tests](https://github.com/SallingGroup-AI-and-ML/venv-cli/actions/workflows/run_tests.yml/badge.svg)](https://github.com/SallingGroup-AI-and-ML/venv-cli/actions/workflows/run_tests.yml)
 ![GitHub License](https://img.shields.io/github/license/SallingGroup-AI-and-ML/venv-cli)
 
-# venv-cli - A CLI tool to create and manage virtual python environments.
+# venv-cli - A CLI tool to create and manage virtual python environments
 
 ## Overview
+
 `venv-cli` is a CLI tool to help create and manage virtual python environments.
 It is built on `pip` and `python -m venv`, and so only requires packages that are already part of the core python installation; no third-party python packages required. This alleviates the bootstrapping problem of needing to install a python package using your system `python` and `pip` before you are able to create virtual environments.
 
@@ -12,40 +13,52 @@ You also don't need `conda`, `pyenv`, `pythonz` etc. to manage your python versi
 ## Installation
 
 Clone this repository, then run the `install.sh` script:
+
 ```console
 $ ./install.sh
 ```
+
 This will install the `venv` source file, along with an uninstall script, in `/usr/local/share/venv/`, and add a line in the appropriate shell `rc`-file (e.g. `~/.bashrc`) sourcing the `venv` source script.
 
 The default shell is `bash`. To install for a different shell, specify the shell name, e.g.
+
 ```console
 $ ./install.sh zsh
 ```
 
 The installation makes the `venv` command available in your terminal. To check if it works, restart the terminal and run
+
 ```console
 $ venv --version
 venv-cli 1.0.0
 ```
 
 # Uninstall
+
 To uninstall `venv` and remove all files, run the uninstall script placed at `/usr/local/share/venv/`:
+
 ```console
 $ bash /usr/local/share/venv/uninstall.sh
 ```
+
 The script should be run by the user that ran the install script to correctly remove the sourcing lines from the `rc`-file of that user. However, since it also cleans up the files in `/usr/share/local/venv/`, it will ask for `sudo` access.
 
 ## Usage
 
 To see the help menu, along with a list of available commands, run `venv -h/--help`.
 
 **In the following sections it is assumed that the working directory is the folder `~/project`.**
+
 ### Create virtual environment
+
 To create a virtual environment, use the command
+
 ```console
 $ venv create <python-version>
 ```
+
 e.g.
+
 ```console
 $ venv create 3.9
 ```
@@ -57,28 +70,37 @@ $ venv create 3.9 venv-name
 ```
 
 If you don't have the specific version of python installed yet, you can get it by running
+
 ```console
 $ sudo apt install python<version>
 ```
+
 e.g.
+
 ```console
 $ sudo apt install python3.10
 ```
+
 (or in the case of Debian-based distributions, like Ubuntu, `sudo apt install python3.10-venv`. The `-venv` part is necessary to be able to use the system python to create virtual environments.)
 
 ## Activating and deactivating the virtual environment
+
 To activate the virtual environment, place yourself _in the folder containing_ the `.venv` folder, then run
+
 ```console
 $ venv activate
 ```
 
 To deactivate it again, run
+
 ```console
 $ venv deactivate
 ```
 
 ## Install/uninstall packages and requirements
+
 To install a single package, simply run
+
 ```console
 $ venv install <package>
 ```
@@ -93,23 +115,31 @@ Unlike `pip install <package>`, which leaves no trace, this ensures that the `re
 In the same spirit, `venv uninstall <package>` first removes the package from `requirements.txt`, then runs `venv install -r requirements.txt` to reinstall the environment from scratch. Unlike `pip uninstall <package>`, this ensures that the uninstall does not leave any "orphaned" packages in the current environment (packages that were installed as secondary dependencies, but are no longer needed since the primary dependency has been uninstalled).
 
 ### Requirements files
+
 To specify a different requirements file to install to/uninstall from, use `-r <requirements>` :
+
 ```console
 $ venv install numpy 'pandas >= 2.0' -r core.txt
 ```
+
 This will add `numpy` and `pandas >= 2.0` as requirements in `core.txt`, then install from that file. Similarly,
+
 ```console
 $ venv uninstall pandas -r core.txt
 ```
+
 will remove the `pandas >= 2.0` requirement from `core.txt` again, then reinstall the environment using the updated `core.txt`.
 
 ### Lock files
+
 When installing or uninstalling packages, the resulting environment is _locked_ into a corresponding `.lock`-file, e.g. running `venv install -r requirements.txt` will lock the installed packages into `requirements.lock`[^1].
 
 This file is useful if a reproducible install is needed, e.g. when deploying a project to a different machine, or when running a colleagues project. Where `requrements.txt` is used to specify the packages and version your project _needs_ (and nothing more), installing from `requirements.lock` makes sure that you get the exact version of every package.
 
 ### Additional requirements
+
 If you have both production and development package requirements, keep them in separate requirements-files, e.g. `requirements.txt` for production requirements and `test.txt` for requirements needed when running tests. An example of these could be:
+
 ```bash
 # requirements.txt
 numpy
@@ -123,19 +153,23 @@ pytest-cov
 ```
 
 You can then use either
+
 ```console
 $ venv install -r requirements.txt
 ```
 
 To install production requirements only, or
+
 ```console
 $ venv install -r test.txt
 ```
 
 to install both production and test requirements. The `-r requirements.txt` in `test.txt` is what makes sure that installing test requirements also installs the requirements from `requirements.txt`.
 
 ## Clearing the environment
+
 If you want to manually clear the environment, you can run
+
 ```console
 $ venv clear
 ```
@@ -151,28 +185,35 @@ $ venv install requirements.txt
 ```
 
 ## Deleting the environment
+
 To completely delete the virtual environment and everything in it, run
+
 ```console
 $ venv delete
 ```
 
 (this will not delete any requirement or .lock-files). This will ask for confirmation before deleting the virtual environment. To give immediate confirmation, pass the `-y` flag:
+
 ```console
 $ venv delete -y
 ```
 
 ## Contributing
+
 Before creating a pull request, please open an issue first to discuss what you would like to change.
 
 To contribute, clone the repo and create a branch, create a virtual environment and install `dev-requirements.txt`. When you are done with your changes, run the test suite with
+
 ```console
 $ pytest .
 ```
+
 then create a pull request for the `main` branch.
 
 Every (public) subcommand has its own test file `tests/test_venv_<command>.py` Please make sure to add/update tests as appropriate.
 
 ### Branches
+
 When creating a new branch, please prefix them with one of the following:
 
 ```
@@ -199,5 +240,5 @@ Then commit the changes, push to `main`, and create a new release on GitHub with
 
 [MIT](https://choosealicense.com/licenses/mit/)
 
-[^1]: A current limitation of using `pip freeze` under the hood is that installing packages from a version control system (VCS) URL that requires authentication, e.g. `private_package @ git+https://USERNAME:PASSWORD@github.com/my-user/private-package`, the authentication is not locked (see https://github.com/pypa/pip/issues/12365).
-These credentials can either be inserted manually into the generated `.lock`-file, or the credentials can instead be stored in a `.netrc` file, which `pip install` will then reference when running `pip install`: https://pip.pypa.io/en/stable/topics/authentication/#netrc-support
+[^1]: A current limitation of using `pip freeze` under the hood is that installing packages from a version control system (VCS) URL that requires authentication, e.g. `private_package @ git+https://USERNAME:PASSWORD@github.com/my-user/private-package`, the authentication is not locked (see [https://github.com/pypa/pip/issues/12365](https://github.com/pypa/pip/issues/12365)).
+These credentials can either be inserted manually into the generated `.lock`-file, or the credentials can instead be stored in a `.netrc` file, which `pip install` will then reference when running `pip install`: [https://pip.pypa.io/en/stable/topics/authentication/#netrc-support](https://pip.pypa.io/en/stable/topics/authentication/#netrc-support)