feat: Add functionality to use code-embedder as a pre-commit hook

feat: Add functionality to use code-embedder as a pre-commit hook

Author: kvankova

.github/workflows/release.yml

@@ -27,13 +27,21 @@ jobs:
           sed -i "s/^version = .*/version = \"$TAG\"/" pyproject.toml
           cat pyproject.toml
 
-      - name: Update README.md
+      - name: Update README.md - Github Action version
         env:
           TAG: ${{ steps.read_tag.outputs.TAG }}
         run: |
           sed -i "s/kvankova\/code-embedder@.*/kvankova\/code-embedder@$TAG/" README.md
           cat README.md
 
+      - name: Update README.md - Pre-commit version
+        env:
+          TAG: ${{ steps.read_tag.outputs.TAG }}
+        run: |
+          sed -i "s/code-embedder==.*/code-embedder==$TAG/" README.md
+          sed -i "s/rev: v[0-9]\+\.[0-9]\+\.[0-9]\+/rev: $TAG/" README.md
+          cat README.md
+
       - name: Commit and push changes
         env:
           TAG: ${{ steps.read_tag.outputs.TAG }}

.pre-commit-hooks.yaml

@@ -0,0 +1,6 @@
+- id: code-embedder
+  name: Code embedder
+  description: >
+    Keep your code snippets in README up-to-date!
+  entry: code-embedder
+  language: python

README.md

@@ -5,26 +5,26 @@
 ## **Code Embedder**
 Seamlessly update code snippets in your **README** files! 🔄📝🚀
 
-[Description](#-description) • [How it works](#-how-it-works) • [Setup](#-setup) • [Examples](#-examples) • [Contributing](#-contributing) • [Development](#️-development)
+[Description](#-description) • [How it works](#-how-it-works) • [Setup - Github Action](#-setup---github-action) • [Setup - Pre-commit Hook](#-setup---pre-commit-hook) • [Examples](#-examples) • [Contributing](#-contributing) • [Development](#️-development)
 </div>
 
 
 ## 📚 Description
 
-**Code Embedder** is a GitHub Action that automatically updates code snippets in your markdown (`README`) files. It finds code blocks in your `README` that reference specific scripts, then replaces these blocks with the current content of those scripts. This keeps your documentation in sync with your code.
+**Code Embedder** is a **GitHub Action** and a **pre-commit hook** that automatically updates code snippets in your markdown (`README`) files. It finds code blocks in your `README` that reference specific scripts, then replaces these blocks with the current content of those scripts. This keeps your documentation in sync with your code.
 
 ### ✨ Key features
 - 🔄 **Automatic synchronization**: Keep your `README` code examples up-to-date without manual intervention.
-- 🛠️ **Easy setup**: Simply add the action to your GitHub workflow and format your `README` code blocks.
-- 📝 **Section support**: Update only specific sections of the script in the `README`.
+- 🛠️ **Easy setup**: Simply add the action to your GitHub workflow / pre-commit hook and format your `README` code blocks.
+- 📝 **Section support**: Update only specific sections of the script in the `README`. This is **language agnostic**.
 - 🧩 **Object support**: Update only specific objects (functions, classes) in the `README`. *The latest version supports only 🐍 Python objects (other languages to be added soon).*
 
 
-By using **Code Embedder**, you can focus on writing and updating your actual code 💻, while letting the action take care of keeping your documentation current 📚🔄. This reduces the risk of outdated or incorrect code examples in your project documentation.
+By using **Code Embedder**, you can focus on writing and updating your actual code 💻, while letting the Code-Embedder take care of keeping your documentation current 📚🔄. This reduces the risk of outdated or incorrect code examples in your project documentation.
 
 ## 🔍 How it works
 
-The action looks for specific tags in all markdown (`README`) files, which indicate the script file path (and optionally the section to update), then it updates the code block sections in the `README` files with the content. The changes are then pushed to the repository 🚀.
+The **Code Embedder** scans markdown files for special tags that specify which parts of your scripts to embed. When it finds these tags, it automatically updates the code blocks with the latest content from your source files. When used as a GitHub Action, any changes are automatically committed and pushed to your repository 🚀.
 
 ### 📄 **Full script** updates
 In the `README` (or other markdown) file, the full script is marked with the following tag:
@@ -47,7 +47,9 @@ You must also add the following comment tags in the script file `path/to/script`
 ...
 [Comment sign] code_embedder:section_name end
 ```
-The comment sign is the one that is used in the script file, e.g. `#` for Python, or `//` for JavaScript. The `section_name` must be unique in the file, otherwise the action will use the first section found.
+The comment sign is the one that is used in the script file, e.g. `#` for Python, or `//` for JavaScript. For example, in python script you add `# code_embedder:A start` and `# code_embedder:A end` to new lines to mark the start and end of the section `A` you want to include in the `README`.
+
+The `section_name` must be unique in the file, otherwise the Code-Embedder will use the first section found.
 
 ### 🧩 **Object** updates
 In the `README` (or other markdown) file, the object of the script is marked with the following tag:
@@ -59,10 +61,10 @@ In the `README` (or other markdown) file, the object of the script is marked wit
 > Notice that the `path/to/script` is followed by `o:` in the tag to indicate that the object `object_name` is being updated.
 
 > [!Note]
-> The object name must match exactly the name of the object (function, class) in the script file, including the case (e.g. `Person` not `person`). Currently, only 🐍 Python objects are supported.
+> The object name must match exactly the name of the object (function, class) in the script file, including the case (e.g. if class is `Person` then object name must be `Person`, not `person`). Currently, only 🐍 Python objects are supported.
 
-## 🔧 Setup
-To use this action, you need to configure a yaml workflow file in `.github/workflows` folder (e.g. `.github/workflows/code-embedder.yaml`) with the following content:
+## 🔧 Setup - Github Action
+Use **Code Embedder** as a Github Action by adding the following to your `.github/workflows/code-embedder.yaml` file:
 
 ```yaml
 name: Code Embedder
@@ -89,6 +91,48 @@ jobs:
 
 ```
 
+## 🔧 Setup - Pre-commit Hook
+You can set up **Code Embedder** as a pre-commit hook using either:
+<ol type="A">
+   <li>Installation via PyPI</li>
+   <li>Direct repository reference in your <code>.pre-commit-config.yaml</code> file</li>
+</ol>
+
+### A. Installation via PyPI
+Install the package:
+```bash
+pip install code-embedder==0.5.2
+```
+
+Your `.pre-commit-config.yaml` file should look like this:
+```yaml
+- repo: local
+  hooks:
+    - id: code-embedder
+      name: Code embedder
+      entry: code-embedder run
+      language: python
+```
+
+### B. Direct repository reference
+Alternatively, you can reference the repository directly in your `.pre-commit-config.yaml` file:
+```yaml
+- repo: https://github.com/kvankova/code-embedder
+  rev: v0.5.2
+  hooks:
+    - id: code-embedder
+      name: Code embedder
+      entry: code-embedder run
+      language: python
+```
+
+### 🔧 Options
+Command `code-embedder run` has the following options:
+
+| Option | Description |
+| ------ | ----------- |
+| `--all-files` | Process all files in the repository. In pre-commit hook, it by default checks only the changed files. |
+
 ## 💡 Examples
 
 ### 📄 Full script update
@@ -107,7 +151,7 @@ The `main.py` file contains the following code:
 print("Embedding successful")
 ```
 
-Once the workflow runs, the code block sections are filled with the content of the script located at `main.py` and updated in the `README` file.
+Once code-embedder runs, the code block sections are filled with the content of the script located at `main.py` and updated in the `README` file.
 
 ````md
 # README
@@ -118,7 +162,7 @@ This is a readme.
 print("Embedding successful")
 ```
 ````
-With any changes to `main.py`, the code block section is updated in the `README` file with the next workflow run.
+With any changes to `main.py`, the code block section is updated in the `README` file with the next code-embedder run.
 
 ### 📂 Section update
 
@@ -140,7 +184,7 @@ print("Embedding successful")
 # code_embedder:A end
 ```
 
-Once the workflow runs, the code block section will be updated in the `README` file with the content of the section `A` from the script located at `main.py` and pushed to the repository 🚀.
+Once code-embedder runs, the code block section will be updated in the `README` file with the content of the section `A` from the script located at `main.py` (in case of using it as a Github Action, the changes are then pushed to the repository 🚀).
 
 ````md
 # README
@@ -152,7 +196,7 @@ print("Embedding successful")
 ```
 ````
 
-With any changes to the section `A` in `main.py`, the code block section is updated in the `README` file with the next workflow run.
+With any changes to the section `A` in `main.py`, the code block section is updated in the `README` file with the next code-embedder run.
 
 ### 🧩 Object update
 The tag used for object update follows the same convention as the tag for section update with the following changes:
@@ -192,7 +236,7 @@ class Person:
 ...
 ```
 
-Once the workflow runs, the code block section will be updated in the `README` file with the content of the function `print_hello` and class `Person` from the script located at `main.py` and pushed to the repository 🚀.
+Once code-embedder runs, the code block section will be updated in the `README` file with the content of the function `print_hello` and class `Person` from the script located at `main.py` (in case of using it as a Github Action, the changes are then pushed to the repository 🚀).
 
 ````md
 # README
@@ -215,10 +259,10 @@ class Person:
 ```
 ````
 
-With any changes to the function `print_hello` or class `Person` in `main.py`, the code block sections are updated in the `README` file with the next workflow run.
+With any changes to the function `print_hello` or class `Person` in `main.py`, the code block sections are updated in the `README` file with the next code-embedder run.
 
 ## 🤝 Contributing
-We welcome contributions to improve this tool!
+We welcome contributions to improve this package!
 - If you have an idea for a **new feature** ✨, open a [new feature request](https://github.com/kvankova/code-embedder/issues/new?labels=enhancement&template=feature_request.yaml) on GitHub.
 - If you spot a **bug** 🐛, open a [new issue](https://github.com/kvankova/code-embedder/issues/new/choose) on GitHub.
 - If you want to **contribute to the code**, please pick an issue that is not assigned to anyone and comment on it, so that we know you are working on it.

entrypoint.sh

@@ -4,15 +4,17 @@ git config --global user.name "github-actions"
 git config --global user.email "github-actions@github.com"
 git remote set-url origin https://x-access-token:$GITHUB_TOKEN@github.com/$GITHUB_REPOSITORY.git
 
-README_PATHS=$(find . -name "*.md" -print)
-
 BRANCH_NAME=${GITHUB_HEAD_REF:-$GITHUB_REF_NAME}
 
 git pull origin ${BRANCH_NAME}
 
 echo "Searching for code snippets in $README_PATHS..."
 
-poetry run python /app/src/main.py --readme-paths $README_PATHS
+poetry run python /app/src/main.py
+
+if [ $? -ne 0 ]; then
+    exit 1
+fi
 
 if [ -n "$(git status -s)" ]; then