DOC: Fix typos and other possible issues detected by PyCharm (#3381)

Author: stefan6419846

.github/workflows/github-ci.yaml

@@ -220,7 +220,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
-          # Use latest Python, so it understands all syntax.
+          # Use the latest Python, so it understands all syntax.
           python-version: ${{ env.PYTHON_LATEST }}
 
       - run: python -m pip install --upgrade coverage[toml]

.github/workflows/release.yaml

@@ -1,8 +1,8 @@
 # This action assumes that there is a REL-commit which already has a
-# Markdown-formatted git tag. Hence the CHANGELOG is already adjusted
+# Markdown-formatted git tag. Hence, the CHANGELOG is already adjusted,
 # and it's decided what should be in the release.
 # This action only ensures the release is done with the proper contents
-# and that it's announced with a Github release.
+# and that it's announced with a GitHub release.
 name: Create git tag
 on:
   push:

docs/conf.py

@@ -64,7 +64,7 @@
 }
 
 nitpick_ignore_regex = [
-    # For reasons unclear at this stage the io module prefixes everything with _io
+    # For reasons unclear at this stage, the io module prefixes everything with _io
     # and this confuses sphinx
     (
         r"py:class",
@@ -131,4 +131,4 @@
 napoleon_google_docstring = True
 napoleon_numpy_docstring = False  # Explicitly prefer Google style docstring
 napoleon_use_param = True  # for type hint support
-napoleon_use_rtype = False  # False so the return type is inline with the description.
+napoleon_use_rtype = False  # False, so the return type is inline with the description.

docs/dev/cmaps.md

@@ -29,15 +29,15 @@ CMapName currentdict /CMap defineresource pop
 
 ## codespacerange
 
-A codespacerange maps a complete sequence of bytes to a range of unicode glyphs.
+A codespacerange maps a complete sequence of bytes to a range of Unicode glyphs.
 It defines a starting point:
 
 ```text
 1 beginbfchar
 <1B> <FB00>
 ```
 
-That means that `1B` (Hex for 27) maps to the unicode character [`FB00`](https://unicode-table.com/en/FB00/) - the ligature ff (two lowercase f's).
+That means that `1B` (Hex for 27) maps to the Unicode character [`FB00`](https://unicode-table.com/en/FB00/) - the ligature ff (two lowercase f's).
 
 The two numbers in `begincodespacerange` mean that it starts with an offset of
 0 (hence from `1B ➜ FB00`) up to an offset of FF (dec: 255), hence 1B+FF = 282
@@ -49,4 +49,4 @@ Within the text stream, there is
 (The)-342(mis\034ts.)
 ```
 
-`\034 ` is octal for 28 decimal.
+`\034 ` is octal for the decimal value 28.

docs/dev/deprecations.md

@@ -2,7 +2,7 @@
 
 pypdf strives to be an excellent library for its current users and for new
 ones. We are careful with introducing potentially breaking changes, but we
-will do them if they provide value for the community on the long run.
+will do them if they provide value for the community in the long run.
 
 We hope and think that deprecations will not happen frequently. If they do,
 users can rely on the following procedure.
@@ -20,8 +20,8 @@ If you are using [Poetry](https://pypi.org/project/poetry/) it is done with the
 
 ## How pypdf deprecates features
 
-Assume the current version of pypdf is `x.y.z`. After a discussion (e.g. via
-GitHub issues) we decided to remove a class / function / method. This is how
+Assume the current version of pypdf is `x.y.z`. After a discussion (e.g., via
+GitHub issues), we decided to remove a class / function / method. This is how
 we do it:
 
 1. `x.y.(z+1)`: Add a DeprecationWarning. If there is a replacement,
@@ -35,7 +35,7 @@ we do it:
    The CHANGELOG informs about it.
 3. `(x+2).0.0`: The DeprecationErrors are removed.
 
-This means the users have 3 warnings in the CHANGELOG, a DeprecationWarning
+This means the users have three warnings in the CHANGELOG, a DeprecationWarning
 until the next major release and a DeprecationError until the major release
 after that.
 

docs/dev/intro.md

@@ -23,7 +23,7 @@ most cases we typically want to test for. The `sample-files` might cover a lot
 more edge cases, the behavior we get when file sizes get bigger, different
 PDF producers.
 
-In order to get the sample-files folder, you need to execute:
+To get the sample-files folder, you need to execute:
 
 ```
 git submodule update --init
@@ -59,26 +59,26 @@ BODY
 
 The `PREFIX` can be:
 
-* `SEC`: Security improvements. Typically an infinite loop that was possible.
-* `BUG`: A bug was fixed. Likely there is one or multiple issues. Then write in
+* `SEC`: Security improvements. Typically, an infinite loop that was possible.
+* `BUG`: A bug was fixed. Likely there are one or multiple issues. Then write in
    the `BODY`: `Closes #123` where 123 is the issue number on GitHub.
    It would be absolutely amazing if you could write a regression test in those
    cases. That is a test that would fail without the fix.
    A bug is always an issue for pypdf users - test code or CI that was fixed is
    not considered a bug here.
 * `ENH`: A new feature! Describe in the body what it can be used for.
-* `DEP`: A deprecation. Either marking something as "this is going to be removed"
+* `DEP`: Deprecation. Either marking something as "this is going to be removed"
    or actually removing it.
 * `PI`: A performance improvement. This could also be a reduction in the
         file size of PDF files generated by pypdf.
 * `ROB`: A robustness change. Dealing better with broken PDF files.
 * `DOC`: A documentation change.
 * `TST`: Adding or adjusting tests.
-* `DEV`: Developer experience improvements, e.g. pre-commit or setting up CI.
-* `MAINT`: Quite a lot of different stuff. Performance improvements are for sure
+* `DEV`: Developer experience improvements, e.g., pre-commit or setting up CI.
+* `MAINT`: Quite a lot of different stuff. Performance improvements are, for sure,
            the most interesting changes in here. Refactorings as well.
 * `STY`: A style change. Something that makes pypdf code more consistent.
-         Typically a small change. It could also be better error messages for
+         Typically, a small change. It could also be better error messages for
          end users.
 
 The prefix is used to generate the CHANGELOG. Every PR must have exactly one -
@@ -89,13 +89,13 @@ your PR.
 
 Smaller Pull Requests (PRs) are preferred as it's typically easier to merge
 them. For example, if you have some typos, a few code-style changes, a new
-feature, and a bug-fix, that could be 3 or 4 PRs.
+feature, and a bug-fix, that could be three or four PRs.
 
-A PR must be complete. That means if you introduce a new feature it must be
+A PR must be complete. That means if you introduce a new feature, it must be
 finished within the PR and have a test for that feature.
 
 ## Benchmarks
 
-We need to keep an eye on performance and thus we have a few benchmarks.
+We need to keep an eye on performance, and thus we have a few benchmarks.
 
 See [py-pdf.github.io/pypdf/dev/bench](https://py-pdf.github.io/pypdf/dev/bench/)

docs/dev/pypdf-writing.md

@@ -43,11 +43,10 @@ our choices.
 with a serialize method which roughly maps to `pypdf.PdfObject.write_to_stream`.
 Some other similarities include:
 
-* [fpdf.output.OutputProducer.buffersize](https://github.com/PyFPDF/fpdf2/blob/master/fpdf/output.py#L370-L485) vs {py:meth}`pypdf.PdfWriter.write_stream <pypdf.PdfWriter.write_stream>`
-* [fpdpf.syntax.Name](https://github.com/PyFPDF/fpdf2/blob/master/fpdf/syntax.py#L124) vs {py:class}`pypdf.generic.NameObject <pypdf.generic.NameObject>`
-* [fpdf.syntax.build_obj_dict](https://github.com/PyFPDF/fpdf2/blob/master/fpdf/syntax.py#L222) vs {py:class}`pypdf.generic.DictionaryObject <pypdf.generic.DictionaryObject>`
-* [fpdf.structure_tree.NumberTree](https://github.com/PyFPDF/fpdf2/blob/master/fpdf/structure_tree.py#L17) vs
- {py:class}`pypdf.generic.TreeObject <pypdf.generic.TreeObject>`
+* [fpdf.output.OutputProducer.buffersize](https://github.com/PyFPDF/fpdf2/blob/master/fpdf/output.py#L370-L485) vs. {py:meth}`pypdf.PdfWriter.write_stream <pypdf.PdfWriter.write_stream>`
+* [fpdpf.syntax.Name](https://github.com/PyFPDF/fpdf2/blob/master/fpdf/syntax.py#L124) vs. {py:class}`pypdf.generic.NameObject <pypdf.generic.NameObject>`
+* [fpdf.syntax.build_obj_dict](https://github.com/PyFPDF/fpdf2/blob/master/fpdf/syntax.py#L222) vs. {py:class}`pypdf.generic.DictionaryObject <pypdf.generic.DictionaryObject>`
+* [fpdf.structure_tree.NumberTree](https://github.com/PyFPDF/fpdf2/blob/master/fpdf/structure_tree.py#L17) vs. {py:class}`pypdf.generic.TreeObject <pypdf.generic.TreeObject>`
 
 
 ### pdfrw

docs/dev/releasing.md

@@ -6,7 +6,7 @@ A `pypdf` release contains the following artifacts:
 * A [release commit](https://github.com/py-pdf/pypdf/commit/91391b18bb8ec9e6e561e2795d988e8634a01a50)
     * Containing a changelog update
     * A new [git tag](https://github.com/py-pdf/pypdf/tags)
-        * A [Github release](https://github.com/py-pdf/pypdf/releases/tag/3.15.0)
+        * A [GitHub release](https://github.com/py-pdf/pypdf/releases/tag/3.15.0)
 
 ## Who does it?
 
@@ -47,7 +47,7 @@ The release contains the following steps:
 4. Wait for the approval of another eligible maintainer.
 5. Merge the pull request with the name being the PR title and the body being
    the content of `RELEASE_COMMIT_MSG.md`.
-7. CI now builds a source and a wheels package which it pushes to PyPI. It also
+6. CI now builds a source and a wheels package which it pushes to PyPI. It also
    creates the corresponding tag and a GitHub release.
 
 ### The Release Tag

docs/dev/testing.md

@@ -2,15 +2,15 @@
 
 pypdf uses [`pytest`](https://docs.pytest.org/en/7.1.x/) for testing.
 
-To run the tests you need to install the CI (Continuous Integration) requirements by running `pip install -r requirements/ci.txt` or
+To run the tests, you need to install the CI (Continuous Integration) requirements by running `pip install -r requirements/ci.txt` or
 `pip install -r requirements/ci-3.11.txt` if running Python ≥ 3.11.
 
 ## Deselecting groups of tests
 
 pypdf makes use of the following pytest markers:
 
 * `slow`: Tests that require more than 5 seconds.
-* `samples`: Tests that require the [the `sample-files` git submodule](https://github.com/py-pdf/sample-files) to be initialized. As of October 2022, this is about 25 MB.
+* `samples`: Tests that require [the `sample-files` git submodule](https://github.com/py-pdf/sample-files) to be initialized. As of October 2022, this is about 25 MB.
 * `enable_socket`: Tests that download PDF documents. They are stored locally and thus only need to be downloaded once. As of October 2022, this is about 200 MB.
   * To successfully run the tests, please download most of the documents beforehand: `python -c "from tests import download_test_pdfs; download_test_pdfs()"`
 

docs/meta/changelog-v1.md

@@ -255,7 +255,7 @@ large PDF files (#808) 🎉
 ### Maintenance (MAINT)
 -  Validate PDF magic byte in strict mode (#814)
 -  Make PdfFileMerger.addBookmark() behave life PdfFileWriters' (#339)
--  Quadratic runtime while parsing reduced to linear  (#808)
+-  Quadratic runtime while parsing reduced to linear (#808)
 
 ### Testing (TST)
 -  Newlines in text extraction (#807)
@@ -403,7 +403,7 @@ large PDF files (#808) 🎉
 - BUG: Error in Chinese character encoding (#463)
 - BUG: Code duplication in Scripts/2-up.py
 - ROBUST: Guard 'obj.writeToStream' with 'if obj is not None'
-- ROBUST: Ignore a /Prev entry with the value 0 in the trailer
+- ROBUST: Ignore a /Prev entry with value 0 in the trailer
 - MAINT: Remove Sample_Code (#726)
 - TST: Close file handle in test_writer (#722)
 - TST: Fix test_get_images (#730)
@@ -449,15 +449,14 @@ Features:
 
 ### Tests and Test setup (TST)
 
- - Add Github Action which automatically run unit tests via pytest and
+ - Add GitHub Action which automatically runs unit tests via pytest and
    static code analysis with Flake8 (#660)
  - Add several unit tests (#661, #663)
  - Add .coveragerc to create coverage reports
 
 ### Developer Experience Improvements (DEV)
 
- - Pre commit: Developers can now `pre-commit install` to avoid tiny issues
-               like trailing whitespaces
+ - Pre commit: Developers can now `pre-commit install` to avoid tiny issues like trailing whitespaces
 
 ### Miscellaneous