Update README, add find/replace with style to document (#12)

* Update README, add find/replace with style to document

* Remove pytest import in example

Author: reindervdw-cmi

README.md

@@ -1,20 +1,4 @@
-[![DOI](https://zenodo.org/badge/657341621.svg)](https://zenodo.org/doi/10.5281/zenodo.10383685)
-
-# CMI-DAIR Template Python Repository
-
-Welcome to the CMI-DAIR Template Python Repository! This template is designed to streamline your project setup and ensure a consistent structure. To get started, follow these steps:
-
-
-- [x] Run `setup_template.py` to initialize the repository.
-- [ ] Replace the content of this `README.md` with details specific to your project.
-- [ ] Install the `pre-commit` hooks to ensure code quality on each commit.
-- [ ] Revise SECURITY.md to reflect supported versions or remove it if not applicable.
-- [ ] Remove the placeholder src and test files, these are there merely to show how the CI works.
-- [ ] If it hasn't already been done for your organization/acccount, grant third-party app permissions for CodeCov.
-- [ ] To set up an API documentation website, after the first successful build, go to the `Settings` tab of your repository, scroll down to the `GitHub Pages` section, and select `gh-pages` as the source. This will generate a link to your API docs.
-- [ ] Update stability badge in `README.md` to reflect the current state of the project. A list of stability badges to copy can be found [here](https://github.com/orangemug/stability-badges). The [node documentation](https://nodejs.org/docs/latest-v20.x/api/documentation.html#documentation_stability_index) can be used as a reference for the stability levels.
-
-# Project name
+# CMI-docx
 
 [![Build](https://github.com/childmindresearch/cmi-docx/actions/workflows/test.yaml/badge.svg?branch=main)](https://github.com/childmindresearch/cmi-docx/actions/workflows/test.yaml?query=branch%3Amain)
 [![codecov](https://codecov.io/gh/childmindresearch/cmi-docx/branch/main/graph/badge.svg?token=22HWWFWPW5)](https://codecov.io/gh/childmindresearch/cmi-docx)
@@ -23,38 +7,42 @@ Welcome to the CMI-DAIR Template Python Repository! This template is designed to
 [![LGPL--2.1 License](https://img.shields.io/badge/license-LGPL--2.1-blue.svg)](https://github.com/childmindresearch/cmi-docx/blob/main/LICENSE)
 [![pages](https://img.shields.io/badge/api-docs-blue)](https://childmindresearch.github.io/cmi-docx)
 
-What problem does this tool solve?
+`cmi-docx` is a Python library for manipulating .docx files built on top of `python-docx`. It extends the functionality of `python-docx` by providing additional features and utilities for working with .docx files.
 
 ## Features
 
-- A few
-- Cool
-- Things
+- Find and replace.
+- Insert paragraphs in the middle of a document.
+- Manipulate styles and formatting of paragraphs' substrings.
 
 ## Installation
 
-Install this package via :
+Install this package from pypi using your favorite package manager. For example, using `pip`:
 
 ```sh
-pip install cmi_docx
-```
-
-Or get the newest development version via:
-
-```sh
-pip install git+https://github.com/childmindresearch/cmi-docx
+pip install cmi-docx
 ```
 
 ## Quick start
 
-Short tutorial, maybe with a
+The following example demonstratesa few features of cmi-docx:
 
 ```Python
-import cmi_docx
+import docx
 
-cmi_docx.short_example()
-```
+from cmi_docx import document
 
-## Links or References
+doc = docx.Document()
+paragraph = doc.add_paragraph("Hello, world!")
+extend_document = document.ExtendDocument(doc)
+extend_paragraph = document.ExtendParagraph(paragraph)
 
-- [https://www.wikipedia.de](https://www.wikipedia.de)
+# Find and replace text.
+extend_document.replace("Hello", "Hi", {"bold": True})
+
+# Insert and image
+extend_document.insert_image(index=1, image_path="path/to/image.png")
+
+# Reformat a paragraph
+extend_paragraph.format(italics=True)
+```

src/cmi_docx/document.py

@@ -1,6 +1,7 @@
 """Extends a python-docx Word document with additional functionality."""
 
 import pathlib
+from typing import Any
 
 from docx import document
 from docx.text import paragraph as docx_paragraph
@@ -44,12 +45,15 @@ def find_in_runs(self, needle: str) -> list[run.FindRun]:
             for finder in paragraph.ExtendParagraph(para).find_in_runs(needle)
         ]
 
-    def replace(self, needle: str, replace: str) -> None:
+    def replace(
+        self, needle: str, replace: str, style: dict[str, Any] | None = None
+    ) -> None:
         """Finds and replaces text in a Word document.
 
         Args:
             needle: The text to find.
             replace: The text to replace.
+            style: The style to apply to the replacement text.
 
         """
         run_finder = self.find_in_runs(needle)
@@ -58,7 +62,7 @@ def replace(self, needle: str, replace: str) -> None:
         )
 
         for run_find in run_finder:
-            run_find.replace(replace)
+            run_find.replace(replace, style)
 
     def insert_paragraph_by_text(
         self,

tests/test_document.py

@@ -90,6 +90,20 @@ def test_replace(runs: list[str], needle: str, replace: str, expected: str) -> N
     assert doc.paragraphs[0].text == expected
 
 
+def test_replace_with_style() -> None:
+    """Test replacing text in a document with style."""
+    doc = docx.Document()
+    doc.add_paragraph("Hello, world!")
+    extend_document = document.ExtendDocument(doc)
+
+    extend_document.replace("Hello", "Goodbye", {"bold": True})
+
+    assert doc.paragraphs[0].text == "Goodbye, world!"
+    assert not doc.paragraphs[0].runs[0].bold
+    assert doc.paragraphs[0].runs[1].bold
+    assert doc.paragraphs[0].runs[1].text == "Goodbye"
+
+
 def test_insert_paragraph_by_object() -> None:
     """Test inserting a paragraph into a document."""
     doc = docx.Document()