From c7a07ecd9095fa643f8186ff798aa7e2b139880d Mon Sep 17 00:00:00 2001 From: j-t-1 <120829237+j-t-1@users.noreply.github.com> Date: Tue, 5 Mar 2024 13:52:25 +0000 Subject: [PATCH] DOC: Minor improvements (#2501) --- docs/dev/deprecations.md | 2 +- docs/dev/intro.md | 10 +++++----- docs/dev/releasing.md | 8 ++++---- docs/dev/testing.md | 4 ++-- docs/user/add-watermark.md | 4 ++-- docs/user/adding-pdf-annotations.md | 2 +- docs/user/merging-pdfs.md | 4 ++-- docs/user/reading-pdf-annotations.md | 2 +- docs/user/streaming-data.md | 2 +- docs/user/viewer-preferences.md | 8 ++++---- 10 files changed, 23 insertions(+), 23 deletions(-) diff --git a/docs/dev/deprecations.md b/docs/dev/deprecations.md index 63edccb48..422da83e8 100644 --- a/docs/dev/deprecations.md +++ b/docs/dev/deprecations.md @@ -4,7 +4,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. -We hope and think that deprecations will not happen soon again. If they do, +We hope and think that deprecations will not happen frequently. If they do, users can rely on the following procedure. ## Semantic Versioning diff --git a/docs/dev/intro.md b/docs/dev/intro.md index 6765b4a44..8b84a8a00 100644 --- a/docs/dev/intro.md +++ b/docs/dev/intro.md @@ -35,7 +35,7 @@ Git is a command line application for version control. If you don't know it, you can [play ohmygit](https://ohmygit.org/) to learn it. GitHub is the service where the pypdf project is hosted. While git is free and -open source, GitHub is a paid service by Microsoft - but for free in lot of +open source, GitHub is a paid service by Microsoft, but free in a lot of cases. [pre-commit](https://pypi.org/project/pre-commit/) is a command line application @@ -47,7 +47,7 @@ you `git commit`. ## Commit Messages Having a clean commit message helps people to quickly understand what the commit -was about, without actually looking at the changes. The first line of the +is about, without actually looking at the changes. The first line of the commit message is used to [auto-generate the CHANGELOG](https://github.com/py-pdf/pypdf/blob/main/make_release.py). For this reason, the format should be: @@ -67,14 +67,14 @@ The `PREFIX` can be: 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`: A 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 / adjusting tests. -* `DEV`: Developer experience improvements - e.g. pre-commit or setting up CI +* `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 the most interesting changes in here. Refactorings as well. * `STY`: A style change. Something that makes pypdf code more consistent. diff --git a/docs/dev/releasing.md b/docs/dev/releasing.md index 0310b22db..4de1c14d6 100644 --- a/docs/dev/releasing.md +++ b/docs/dev/releasing.md @@ -13,7 +13,7 @@ A `pypdf` release contains the following artifacts: `pypdf` should typically only be released by one of the core maintainers / the core maintainer. At the moment, this is Martin Thoma. -Any owner of the py-pdf organization has also the technical permissions to +Any owner of the py-pdf organization also has the technical permissions to release. ## How is it done? @@ -21,10 +21,10 @@ release. The release contains the following steps: 1. Update the CHANGELOG.md and the _version.py via `python make_release.py`. - This also prepares the release commit message + This also prepares the release commit message. 2. Create a release commit: `git commit -eF RELEASE_COMMIT_MSG.md`. 3. Tag that commit: `git tag -s {{version}} -eF RELEASE_TAG_MSG.md`. -4. Push both: `git push && git push --tags` +4. Push both: `git push && git push --tags`. 5. CI now builds a source and a wheels package which it pushes to PyPI. It also creates a GitHub release. @@ -33,7 +33,7 @@ The release contains the following steps: ### The Release Tag * Use the release version as the tag name. No need for a leading "v". -* Use the changelog entry as the body +* Use the changelog entry as the body. ## When are releases done? diff --git a/docs/dev/testing.md b/docs/dev/testing.md index c07ef6440..99e5e3cc0 100644 --- a/docs/dev/testing.md +++ b/docs/dev/testing.md @@ -5,11 +5,11 @@ 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 `pip install -r requirements/ci-3.11.txt` if running Python ≥ 3.11. -## De-selecting groups of tests +## Deselecting groups of tests pypdf makes use of the following pytest markers: -* `slow`: Tests that require more than 5 seconds +* `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. * `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()"` diff --git a/docs/user/add-watermark.md b/docs/user/add-watermark.md index f8be962ff..2491fad7f 100644 --- a/docs/user/add-watermark.md +++ b/docs/user/add-watermark.md @@ -1,4 +1,4 @@ -# Adding a Stamp/Watermark to a PDF +# Adding a Stamp or Watermark to a PDF Adding stamps or watermarks are two common ways to manipulate PDF files. A stamp is adding something on top of the document, a watermark is in the @@ -21,7 +21,7 @@ for page in writer.pages: writer.write("out.pdf") ``` -Else use `merge_transformed_page()` with `Transformation()` if you need to translate, rotate, scale, etc. the stamp before merging it to the content page. +Otherwise use `merge_transformed_page()` with `Transformation()` if you need to translate, rotate, scale, etc. the stamp before merging it to the content page. ```python from pathlib import Path diff --git a/docs/user/adding-pdf-annotations.md b/docs/user/adding-pdf-annotations.md index d075d83e1..b22e735d1 100644 --- a/docs/user/adding-pdf-annotations.md +++ b/docs/user/adding-pdf-annotations.md @@ -304,7 +304,7 @@ with open("annotated-pdf.pdf", "wb") as fp: Text markup annotations refer to a specific piece of text within the document. Those are a bit more complicated as you need to know exactly where the text -is. Those are the "Quad points". +is, the so-called "Quad points". ### Highlighting diff --git a/docs/user/merging-pdfs.md b/docs/user/merging-pdfs.md index ca01fa985..a0f4314da 100644 --- a/docs/user/merging-pdfs.md +++ b/docs/user/merging-pdfs.md @@ -63,7 +63,7 @@ writer.append(reader, "page 1 and 10", [0, 9]) During merging, the relevant named destination will also imported. -If you want to insert pages in the middle of the destination, use `merge` (which provides (insertion) position). +If you want to insert pages in the middle of the destination, use `merge` (which provides an insertion position). You can insert the same page multiple times, if necessary even using a list-based syntax: ```python @@ -126,7 +126,7 @@ Please note that if you clone an object, you will clone all the objects below as including the objects pointed by *IndirectObject*. Due to this, if you clone a page that includes some articles (`"/B"`), not only the first article, but also all the chained articles and the pages where those articles can be read will be copied. -It means that you may copy lots of objects which will be saved in the output PDF as well. +This means that you may copy lots of objects which will be saved in the output PDF as well. In order to prevent this, you can provide the list of fields in the dictionaries to be ignored: diff --git a/docs/user/reading-pdf-annotations.md b/docs/user/reading-pdf-annotations.md index 959dbe8a0..4aec76828 100644 --- a/docs/user/reading-pdf-annotations.md +++ b/docs/user/reading-pdf-annotations.md @@ -31,7 +31,7 @@ for page in reader.pages: print(annotation) ``` -Reading the most common ones is described here. +Examples of reading three of the most common annotations: ## Text diff --git a/docs/user/streaming-data.md b/docs/user/streaming-data.md index 8c9ac3a8c..9a0032f08 100644 --- a/docs/user/streaming-data.md +++ b/docs/user/streaming-data.md @@ -3,7 +3,7 @@ In some cases you might want to avoid saving things explicitly as a file to disk, e.g. when you want to store the PDF in a database or AWS S3. -pypdf supports streaming data to a file-like object and here is how. +pypdf supports streaming data to a file-like object: ```python from io import BytesIO diff --git a/docs/user/viewer-preferences.md b/docs/user/viewer-preferences.md index 01fd8ad5c..bda3970ab 100644 --- a/docs/user/viewer-preferences.md +++ b/docs/user/viewer-preferences.md @@ -1,6 +1,6 @@ # Adding Viewer Preferences -It is possible to set viewer preferences of the PDF file. +It is possible to set viewer preferences of a PDF file. These properties are described in Section 12.2 of the [PDF 1.7 specification](https://opensource.adobe.com/dc-acrobat-sdk-docs/pdfstandards/PDF32000_2008.pdf). Note that the `/ViewerPreferences` dictionary does not exist by default. @@ -8,7 +8,7 @@ If it's not already present, it must be created by calling the `create_viewer_pr of the `PdfWriter` object. If viewer preferences exist in a PDF file being read with `PdfReader`, -you can access them as properties of the `viewer_preferences` properties. +you can access them as properties of `viewer_preferences`. Otherwise, the `viewer_preferences` property will be set to `None`. ## Example @@ -78,6 +78,6 @@ with open("output.pdf", "wb") as output_stream: writer.write(output_stream) ``` -(The names beginning with a slash character are part of the PDF file format. They are +The names beginning with a slash character are part of the PDF file format. They are included here to aid to anyone searching pypdf documentation -for these names from the PDF specification.) +for these names from the PDF specification.