closes #261 (#297)

.pre-commit-config.yaml

@@ -2,23 +2,30 @@ repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: v4.5.0
   hooks:
+  # Prevent committing to the master branch
   - id: no-commit-to-branch
     args: [--branch, master]
+  # Format yaml files
   - id: check-yaml
+  # Fix end-of-file issues
   - id: end-of-file-fixer
+  # Fix trailing whitespace
   - id: trailing-whitespace
+  # Prevent debug statements
   - id: debug-statements
   - id: fix-encoding-pragma
   - id: mixed-line-ending
+# Code formatting
 - repo: https://github.com/ambv/black
   rev: 24.2.0
   hooks:
   - id: black
+# Further linting (e.g. module imported but not used)
 - repo: https://github.com/PyCQA/flake8
   rev: 7.0.0
   hooks:
   - id: flake8
-# Make a requirements.txt with poetry every time you commit
+# Verify that requirements.txt is up to date with poetry dependencies every commit
 - repo: https://github.com/python-poetry/poetry
   rev: 1.8.3
   hooks:
@@ -38,7 +45,8 @@ repos:
         "clipboard download express gel",
       ]
       files: 'requirements.txt'
-
+# Remove metadata from jupyter notebooks. This will always be triggered when you commit a change in a notebook.
+# Simply do `git add` and commit again.
 - repo: local
   hooks:
     - id: nbstripout

README.md

@@ -237,10 +237,6 @@ product, *rest = asm.assemble_circular()
 product.figure()
 
 ```
-
-
-
-
      -|fragment_A|13
     |             \/
     |             /\
@@ -254,9 +250,6 @@ product.figure()
     |                                            |
      --------------------------------------------
 
-
-
-
 ```python
 # Or show the final sequence:
 Dseqrecord(product).figure()
@@ -409,13 +402,14 @@ git checkout -b issue_<number>
 
 ### Local development 💻
 
-#### Preferred method (using `poetry`)
+#### Preferred method (using `poetry`) 🧙‍♂️
 
 This is the preferred method to develop on pydna, so if you plan to contribute regularly, it's worth taking this route. If you
-encounter any issues, create an issue on GitHub and we will be able to help.
+encounter any issues setting up the dev environment, create an issue on GitHub and we will be able to help.
 
 Use [Poetry](https://python-poetry.org/docs/#installation) to install dependencies and activate virtual environment. This is necessary
-if you want to edit the project dependencies.
+if you want to edit the project dependencies. Install poetry using [pipx](https://github.com/pypa/pipx) following poetry's installation instructions, do not install it
+in the system python or the project environment.
 
 ```bash
 # If you want the virtual environment to be created in this folder
@@ -432,18 +426,35 @@ poetry shell
 poetry run pre-commit install
 ```
 
-#### Alternative method (using `pip`)
+#### Alternative method (using `pip`) 🐍
 
-TODO
+Use this for a small contribution or if you don't manage to set up the dev environment.
+
+```bash
+# Create a new virtual environment
+python -m venv .venv
+
+# Activate the virtual environment
+source .venv/bin/activate
+
+# Install all dependencies (library deps + dev and test requirements)
+pip install -r requirements.txt
+
+# Install the project as editable dependency
+pip install -e .
+
+# Install the pre-commit hooks
+pre-commit install
+```
 
 #### Contributing code 💻
 
 1. Make your changes.
 2. Add the necessary tests in `tests/`.
 3. Run the tests from the root directory with `python run_test.py`.
    > **TIP:** You can run a particular test file with `pytest -vs test_file.py` (`-v` for verbose and `-s` to see print statements in the test). If you want to run just a single test, you can use `pytest -vs -k test_name`, where `test_name` is the name of the test function.
-4. Install `pre-commit` hooks if you haven't by running `pre-commit install`. `pre-commit` should be available in the environment, since it is installed by poetry.
-   > **TIP:** The hooks are a series of checks that will be run before you commit your code. If any of the checks fail, the commit will not be allowed. Some of them auto-fix the code (e.g., `black` formatting), so you can simply do `git add .` and commit again.
+4. Before committing, install `pre-commit` hooks if you haven't by running `pre-commit install`. `pre-commit` should be available in the environment regardless of the method you use to set up the dev environment.
+   > **TIP:** The hooks are a series of checks that will be run before you commit your code. If any of the checks fail, the commit will not be allowed. Some of them auto-fix the code (e.g., `black` formatting), so you can simply do `git add .` and commit again. Others like `flake8` will prevent the commit to happen until the code is compliant.  For instance, if you import a module in a file and not use it, `flake8` will complain. For a full list of checks, see `.pre-commit-config.yaml`.
 5. Push the changes to your fork
 
 ### Creating a PR 🔗