Merge pull request #911 from chinapandaman/PPF-910

PPF-910: improve doc wordings

Author: chinapandaman

docs/button_style.md

@@ -1,11 +1,10 @@
 # Change checkbox and radio button styles
 
-Similar to text fields discussed in the last chapter, PyPDFForm gives you the ability to 
-modify some styles of checkboxes and radio buttons without changing the template.
+PyPDFForm allows you to modify certain styles of checkboxes and radio buttons without altering the template, similar to text fields.
 
 ## Change size
 
-You can change the size of the selection by specifying a `float` value. Consider 
+To change the size of the selection, specify a `float` value. For an example, refer to
 [this PDF](https://github.com/chinapandaman/PyPDFForm/raw/master/pdf_samples/sample_template.pdf):
 
 ```python
@@ -30,8 +29,8 @@ with open("output.pdf", "wb+") as output:
 
 ## Change button style
 
-The button style is the shape of the selection on a checkbox or radio button. PyPDFForm lets you pick 
-three different button styles: `check`, `circle`, and `cross`. Consider 
+The button style determines the shape of the selection on a checkbox or radio button. PyPDFForm offers
+three button styles: `check`, `circle`, and `cross`. For an example, see
 [this PDF](https://github.com/chinapandaman/PyPDFForm/raw/master/pdf_samples/sample_template_with_radio_button.pdf):
 
 ```python

docs/coordinate.md

@@ -1,13 +1,10 @@
 # PDF coordinates
 
-The coordinate system on a single page of a PDF starts at the bottom left of the page as the origin. The unit of 
-the coordinates is called "points" and there are 72 points/inch.  PyPDFForm utilizes this coordinate system in 
-some of its APIs so that widgets, texts, or images can be created on a PDF.
+The PDF coordinate system originates at the bottom left of the page. The unit of measurement is "points," with 72 points per inch. PyPDFForm uses this coordinate system in its APIs to create widgets, text, or images on a PDF.
 
 ## Generate a coordinate grid view
 
-To allow a better user experience with the coordinate system, PyPDFForm implements a grid view so that there is a 
-better idea on where stuffs should be placed on a PDF.
+To enhance the user experience with the coordinate system, PyPDFForm provides a grid view that helps determine the optimal placement of elements on a PDF.
 
 Consider [this PDF](https://github.com/chinapandaman/PyPDFForm/raw/master/pdf_samples/sample_template.pdf), the 
 coordinate grid view can be generated like this:
@@ -26,6 +23,4 @@ with open("output.pdf", "wb+") as output:
     output.write(grid_view_pdf.read())
 ```
 
-The `generate_coordinate_grid` method takes two optional parameters. The first one is `color` which allows you to pick 
-a color for the grid view. The default color is red. The second one is `margin` which allows you to change the 
-coordinate grid view's margin in points. The default margin is 100 points.
+The `generate_coordinate_grid` method accepts two optional parameters: `color` and `margin`. The `color` parameter sets the grid view color, defaulting to red. The `margin` parameter adjusts the coordinate grid view's margin in points, with a default of 100 points.

docs/dev_changes.md

@@ -1,25 +1,21 @@
 # Pull Request Requirements
 
-Whenever a pull request is submitted, there are some expectations for the content before it can be merged 
-into the master branch.
+When submitting a pull request, certain expectations must be met before it can be merged into the master branch.
 
 ## Code changes
 
-There isn't any strict rule on how coding should be done for PyPDFForm. The project welcomes code contributions from 
-anyone with any level of expertise.
+PyPDFForm doesn't have strict coding rules, welcoming contributions from developers of all expertise levels.
 
 With that said, there are some conventions that are expected to be followed by your PR:
 
-* Small changes are preferred over lengthy changes. If your changes are large, please request a feature branch in your issue 
-and open your PR against that branch, as your changes will likely need to be revised before merging into master.
+* Small, incremental changes are preferred. For large changes, request a feature branch in your issue and open your PR against that branch, as they will likely require revision before merging into master.
 * Your changes must pass [Pylint](https://www.pylint.org/). To check if this is true, simply run `pylint PyPDFForm`.
 * Your changes must pass all tests and have 100% coverage. You can read more about testing [here](dev_test.md).
 * If you are changing the user APIs or any other parts of the code that are relevant, please update the appropriate documentation too.
 
 ## Merge process
 
-Your PR will be reviewed before merging into the master branch. In the case where your changes are too large to leave review comments, 
-you will likely be asked to reopen your PR against a new feature branch so that your changes can be revised/refactored to the appropriate code structure.
+Your PR will undergo review before being merged into the master branch. If your changes are too extensive for inline review comments, you may be asked to reopen your PR against a new feature branch for revision and refactoring.
 
 On top of that, your PR needs to run through some CI checks:
 

docs/dev_doc.md

@@ -1,20 +1,19 @@
 # Hosting Docs Locally
 
-When the changes apply to the user APIs or any other parts of the code that are relevant, the appropriate documentation should 
-also be updated.
+Update the relevant documentation when changing user APIs or other significant code sections.
 
-PyPDFForm uses [MkDocs](https://www.mkdocs.org/) for building the documentation. To host the doc site locally, simply run:
+PyPDFForm uses [MkDocs](https://www.mkdocs.org/) to build its documentation. To host the documentation locally, run:
 
 ```shell
 mkdocs serve
 ```
 
-And you will find the doc site at `http://127.0.0.1:8000/`.
+The documentation will be available at `http://127.0.0.1:8000/`.
 
-Alternatively, in the development container, run:
+Alternatively, to run the documentation in the development container:
 
 ```shell
 docs
 ```
 
-And you will find the doc site at `http://localhost:8000/`.
+The documentation will be available at `http://localhost:8000/`.

docs/dev_intro.md

@@ -1,19 +1,18 @@
 # Developer Intro
 
-PyPDFForm's targeted users are other Python developers. This section of the documentation is not for the users, 
-but for people who want to start making contributions to PyPDFForm itself.
+PyPDFForm is designed for Python developers. This documentation section is intended for contributors to PyPDFForm, not its end-users.
 
 ## Setup
 
-Create a virtual environment, then install all development dependencies using a package manager of your choice.
+To get started, create a virtual environment and install the development dependencies using your preferred package manager.
 
 The command below uses [uv](https://docs.astral.sh/uv/):
 
 ```shell
 uv pip install -r pyproject.toml --extra dev
 ```
 
-Alternatively, PyPDFForm provides a development container. Build it by running this command at the root directory of the project:
+PyPDFForm also offers a development container. To build it, run the following command in the project's root directory:
 
 ```shell
 docker build -t pypdfform-dev .
@@ -31,7 +30,7 @@ See [testing PyPDFForm with pytest](dev_test.md).
 
 ## Creating issues
 
-When you create an issue on GitHub, try your best to follow these conventions:
+When creating a GitHub issue, follow these guidelines:
 
 * The issue title should have the format `PPF-<issue number>: <title of the issue>`.
 * The issue description should be as descriptive as possible, preferably with the following:
@@ -41,7 +40,7 @@ When you create an issue on GitHub, try your best to follow these conventions:
 
 ## Opening pull requests
 
-Please create an issue before making a pull request. Try your best to follow these conventions when doing so:
+Before opening a pull request, create an issue. When opening the pull request, follow these guidelines:
 
 * The PR title should be the same as its respective issue, so `PPF-<issue number>: <title of the issue>`.
 * The PR description should contain a brief explanation of the changes.

docs/dev_release.md

@@ -1,26 +1,26 @@
 # Releasing
 
-A PyPDFForm release starts with the following steps:
+The PyPDFForm release process begins with the following steps:
 
-* A release [issue](https://github.com/chinapandaman/PyPDFForm/issues/686) and [PR](https://github.com/chinapandaman/PyPDFForm/pull/687).
-* A new [GitHub release](https://github.com/chinapandaman/PyPDFForm/releases) with auto-generated changelogs.
+* Creating a release [issue](https://github.com/chinapandaman/PyPDFForm/issues/686) and [PR](https://github.com/chinapandaman/PyPDFForm/pull/687).
+* Publishing a new [GitHub release](https://github.com/chinapandaman/PyPDFForm/releases) with auto-generated changelogs.
 
-Once these steps are done, the CI for deployment will be triggered.
+After completing these steps, the deployment CI will be triggered.
 
 ## Versioning
 
 PyPDFForm follows the conventions defined by [Semantic Versioning](https://semver.org/).
 
 ## Deploy process
 
-When the GitHub release is created, it will trigger two different CIs:
+Creating a GitHub release triggers two CIs:
 
 * [Deploy](https://github.com/chinapandaman/PyPDFForm/actions/workflows/python-publish.yml), which will create the distribution and upload it to [PyPI](https://pypi.org/project/PyPDFForm/).
 * [Deploy Docs](https://github.com/chinapandaman/PyPDFForm/actions/workflows/deploy-docs.yml), which will tear down and rebuild the [GitHub page](https://chinapandaman.github.io/PyPDFForm/) where the doc site is hosted.
 
 ## When are releases done?
 
-It depends on the changes that are currently on the master branch but have not deployed yet. Generally speaking:
+The timing of releases depends on the changes pending deployment on the master branch. Generally:
 
 * Serious bugs are usually released immediately after they are fixed.
 * New features can usually wait and are released on a weekly basis.

docs/dev_test.md

@@ -1,7 +1,7 @@
 # Testing
 
-PyPDFForm uses [pytest](https://pytest.org/) for testing and [coverage.py](https://coverage.readthedocs.io/) 
-for test coverages. Tests can be run by simply executing:
+PyPDFForm uses [pytest](https://pytest.org/) for testing and [coverage.py](https://coverage.readthedocs.io/)
+for measuring test coverage. To run the tests, execute:
 
 ```shell
 coverage run -m pytest && coverage report --fail-under=100
@@ -15,13 +15,13 @@ test
 
 ## Generate coverage report
 
-To generate a coverage report, run:
+To generate a test coverage report, run:
 
 ```shell
 coverage run -m pytest && coverage html
 ```
 
-And the coverage report can be viewed by opening `htmlcov/index.html` in a browser.
+View the coverage report by opening `htmlcov/index.html` in a browser.
 
 Alternatively, in the development container, run:
 
@@ -33,9 +33,9 @@ And the coverage report can be found at `http://localhost:8000/htmlcov/index.htm
 
 ## Test breakdown
 
-Each PyPDFForm test is different. However, there is a general paradigm that almost all tests follow.
+Although each PyPDFForm test is unique, most follow a general paradigm.
 
-In most cases, a test can be verbally summed up into three steps:
+Most tests can be summarized into three steps:
 
 * Define an expected PDF file that the outcome of the test should look like.
 * Execute a sequence of code using PyPDFForm to generate a PDF that should look like the expected PDF file.
@@ -92,7 +92,7 @@ obj = PdfWrapper(
 )
 ```
 
-These two lines should almost always be included in every test to make updating old tests easier:
+Include these two lines in most tests to simplify updating old tests:
 
 ```python
 request.config.results["expected_path"] = expected_path

docs/draw.md

@@ -1,18 +1,15 @@
-# Draw stuffs
+# Draw elements
 
-PyPDFForm allows you to draw certain elements on a PDF. The purpose is in case there is a missing widget on your PDF 
-form, and you need to put certain texts on it, or if you need to draw images.
+PyPDFForm enables drawing elements on a PDF, which is useful when a widget is missing from your PDF form or when you need to add text or images.
 
 This section of the documentation will use 
 [this PDF](https://github.com/chinapandaman/PyPDFForm/raw/master/pdf_samples/sample_template.pdf) as an example.
 
-This section of the documentation requires a basic understanding of [the PDF coordinate system](coordinate.md).
+Understanding [the PDF coordinate system](coordinate.md) is necessary for this section.
 
 All optional parameters will have a comment `# optional` after each of them.
 
-**NOTE:** Due to a known bug in a dependency, it is advised that these draw methods are called after 
-a PDF form is filled. Otherwise, part (most noticeably radio buttons) or even all widgets of the PDF form might 
-get removed after drawing things on it.
+**NOTE:** Due to a known bug in a dependency, call the draw methods after filling the PDF form. Otherwise, some or all widgets, especially radio buttons, might be removed.
 
 ## Draw text
 

docs/fill.md

@@ -1,14 +1,10 @@
 # Fill a PDF form
 
-PyPDFForm uses a single depth, non-nested dictionary to fill a PDF form. As a result of this process, the filled 
-PDF form will be flattened and no longer editable. This is to prevent future encoding issues, especially when 
-multiple PDF forms with overlaps on widget names are combined.
+PyPDFForm fills a PDF form using a flat, non-nested dictionary. The filled form is flattened and becomes non-editable to prevent encoding issues when combining multiple forms with overlapping widget names.
 
 ## Fill text field and checkbox widgets
 
-As seen when we 
-inspected [this PDF](https://github.com/chinapandaman/PyPDFForm/raw/master/pdf_samples/sample_template.pdf), a text 
-field can be filled with a value of `string`, whereas a checkbox can be filled with a `boolean` value:
+When inspecting [this PDF](https://github.com/chinapandaman/PyPDFForm/raw/master/pdf_samples/sample_template.pdf), note that text fields are filled with `string` values and checkboxes with `boolean` values.
 
 ```python
 from PyPDFForm import PdfWrapper
@@ -30,7 +26,7 @@ with open("output.pdf", "wb+") as output:
 
 ## Fill radio button widgets
 
-A radio button group on a PDF form is a collection of radio buttons that share the same name.
+A radio button group is a collection of radio buttons sharing the same name on a PDF form.
 
 A [PDF form](https://github.com/chinapandaman/PyPDFForm/raw/master/pdf_samples/sample_template_with_radio_button.pdf) 
 with radio button groups can be filled using `integer` values where the value indicates which radio button to select 
@@ -53,8 +49,8 @@ with open("output.pdf", "wb+") as output:
 
 ## Fill dropdown widgets
 
-Similar to radio buttons, a dropdown choice can be selected by specifying an `integer` value of the choice. Consider 
-[this PDF](https://github.com/chinapandaman/PyPDFForm/raw/master/pdf_samples/dropdown/sample_template_with_dropdown.pdf):
+Like radio buttons, select a dropdown choice by specifying its `integer` value. For an example, see
+[this PDF](https://github.com/chinapandaman/PyPDFForm/raw/master/pdf_samples/dropdown/sample_template_with_dropdown.pdf).
 
 ```python
 from PyPDFForm import PdfWrapper
@@ -71,8 +67,7 @@ with open("output.pdf", "wb+") as output:
 
 ## Fill signature widgets
 
-A signature field widget allows you to sign a PDF form in a handwritten format. PyPDFForm lets you use a signature image to populate 
-any signature field widget.
+A signature field widget enables signing a PDF form with a handwritten signature image.
 
 Consider [this PDF](https://github.com/chinapandaman/PyPDFForm/raw/master/pdf_samples/signature/sample_template_with_signature.pdf) 
 and [this signature image](https://github.com/chinapandaman/PyPDFForm/raw/master/image_samples/sample_signature.png):
@@ -90,8 +85,7 @@ with open("output.pdf", "wb+") as output:
     output.write(signed.read())
 ```
 
-**NOTE:** As described [here](install.md/#create-a-pdf-wrapper), the value of the signature in your dictionary can be 
-a file path shown above, but also an open file object and a file stream that's in `bytes`.
+**NOTE:** The signature value in your dictionary can be a file path, an open file object, or a `bytes` file stream, as described [here](install.md/#create-a-pdf-wrapper).
 
 By default, the library preserves the aspect ratio of the signature image when filling it. This can be turned off by setting 
 the `preserve_aspect_ratio` property to `False` on the signature widget:
@@ -113,8 +107,7 @@ with open("output.pdf", "wb+") as output:
 
 ## Fill image widgets
 
-An image field widget can be filled similarly to a signature field, by providing a value of file path, file object, or 
-file stream.
+Fill an image field widget similarly to a signature field, using a file path, file object, or file stream.
 
 Consider [this PDF](https://github.com/chinapandaman/PyPDFForm/raw/master/pdf_samples/sample_template_with_image_field.pdf) 
 and [this image](https://github.com/chinapandaman/PyPDFForm/raw/master/image_samples/sample_image.jpg):
@@ -152,8 +145,7 @@ with open("output.pdf", "wb+") as output:
 
 ## Disable rendering widgets
 
-By default, PyPDFForm will still render each widget on the filled PDF form even though it's flattened during filling the process. This behavior can be disabled globally by passing 
-the `render_widgets` parameter as `False` to the `PdfWrapper` object. Consider [this PDF](https://github.com/chinapandaman/PyPDFForm/raw/master/pdf_samples/sample_template.pdf):
+By default, PyPDFForm renders widgets on the filled PDF form despite flattening during the filling process. To disable this globally, pass `render_widgets=False` to the `PdfWrapper` object. For an example, see [this PDF](https://github.com/chinapandaman/PyPDFForm/raw/master/pdf_samples/sample_template.pdf).
 
 ```python
 from PyPDFForm import PdfWrapper
@@ -173,8 +165,7 @@ with open("output.pdf", "wb+") as output:
     output.write(filled.read())
 ```
 
-Alternatively, if you just want to disable rendering of some widgets but not others, you can do so at each widget's level by setting the attribute 
-`render_widget` to `False`:
+To disable rendering for specific widgets, set the `render_widget` attribute to `False` at the individual widget level.
 
 ```python
 from PyPDFForm import PdfWrapper

docs/index.md

@@ -19,7 +19,7 @@ It also supports other common utilities such as extracting pages and merging mul
 * [Fill a PDF form in place](simple_fill.md)
 * [Change text field styles](style.md)
 * [Change checkbox and radio button styles](button_style.md)
-* [Draw stuffs](draw.md)
+* [Draw elements](draw.md)
 * [Other utilities](utils.md)
 
 ## Developer Guide