Skip to content

Commit 2cdc0d5

Browse files
stefan6419846stefan6419846
authored
DOC: Resolve build warnings (#2380)
This fixes #1941 by cleaning up wrong references and adding new docs. Some notes about this: * Building the docs now works without prior package installation. * The intersphinx mapping will now always use the objects of the Python version used for the docs build. * The intersphinx mapping for *Pillow* has been added. * Links to private methods in the developer docs have been replaced by inline code as they are not part of the Sphinx docs. * Some broken/outdated/strange docstrings have been fixed. * New classes have been added to the docs. Module-specific classes have been added to the modules where they are being used directly, some generic classes/modules have been put into new files/pages. * We have to exclude some members to avoid duplicate definitions.
1 parent 2f4f705 commit 2cdc0d5

14 files changed

+109
-33
lines changed

‎docs/conf.py

+5-3
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,11 @@
1414
import shutil
1515
import sys
1616

17-
import pypdf as py_pkg
18-
1917
sys.path.insert(0, os.path.abspath("."))
2018
sys.path.insert(0, os.path.abspath("../"))
2119

20+
import pypdf as py_pkg # noqa: E402
21+
2222
shutil.copyfile("../CHANGELOG.md", "meta/CHANGELOG.md")
2323
shutil.copyfile("../CONTRIBUTORS.md", "meta/CONTRIBUTORS.md")
2424

@@ -57,8 +57,10 @@
5757
"myst_parser",
5858
]
5959

60+
python_version = ".".join(map(str, sys.version_info[:2]))
6061
intersphinx_mapping = {
61-
"python": ("https://docs.python.org/3.8", None),
62+
"python": (f"https://docs.python.org/{python_version}", None),
63+
"Pillow": ("https://pillow.readthedocs.io/en/latest/", None),
6264
}
6365

6466
nitpick_ignore_regex = [

‎docs/dev/pypdf-parsing.md

+1-3
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,7 @@ structure of parsing:
2020
decodes these content streams by applying filters (e.g., `FlateDecode`,
2121
`LZWDecode`) specified in the stream's dictionary. This is only done when the
2222
object is requested via {py:meth}`PdfReader.get_object
23-
<pypdf.PdfReader.get_object>` in the
24-
{py:meth}`PdfReader._get_object_from_stream
25-
<pypdf.PdfReader._get_object_from_stream>` method.
23+
<pypdf.PdfReader.get_object>` in the `PdfReader._get_object_from_stream` method.
2624

2725
## References
2826

‎docs/index.rst

+3
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,9 @@ You can contribute to `pypdf on GitHub <https://github.com/py-pdf/pypdf>`_.
6161
modules/annotations
6262
modules/Fit
6363
modules/PaperSize
64+
modules/constants
65+
modules/errors
66+
modules/generic
6467

6568
.. toctree::
6669
:caption: Developer Guide

‎docs/modules/PageObject.rst

+12
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,15 @@ The PageObject Class
55
:members:
66
:undoc-members:
77
:show-inheritance:
8+
9+
.. autoclass:: pypdf._utils.ImageFile
10+
:members:
11+
:undoc-members:
12+
:show-inheritance:
13+
:exclude-members: IndirectObject
14+
15+
.. autoclass:: pypdf._utils.File
16+
:members:
17+
:undoc-members:
18+
:show-inheritance:
19+
:exclude-members: IndirectObject

‎docs/modules/PdfReader.rst

+5
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,8 @@ The PdfReader Class
55
:members:
66
:undoc-members:
77
:show-inheritance:
8+
9+
.. autoclass:: pypdf.PasswordType
10+
:members:
11+
:undoc-members:
12+
:show-inheritance:

‎docs/modules/PdfWriter.rst

+5
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,8 @@ The PdfWriter Class
55
:members:
66
:undoc-members:
77
:show-inheritance:
8+
9+
.. autoclass:: pypdf.ObjectDeletionFlag
10+
:members:
11+
:undoc-members:
12+
:show-inheritance:

‎docs/modules/constants.rst

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
Constants
2+
---------
3+
4+
.. autoclass:: pypdf.constants.AnnotationFlag
5+
:members:
6+
:undoc-members:
7+
:show-inheritance:
8+
9+
.. autoclass:: pypdf.constants.ImageType
10+
:members:
11+
:undoc-members:
12+
:show-inheritance:
13+
14+
.. autoclass:: pypdf.constants.PageLabelStyle
15+
:members:
16+
:undoc-members:
17+
:show-inheritance:

‎docs/modules/errors.rst

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Errors
2+
------
3+
4+
.. automodule:: pypdf.errors
5+
:members:
6+
:undoc-members:
7+
:show-inheritance:

‎docs/modules/generic.rst

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
Generic PDF objects
2+
-------------------
3+
4+
.. automodule:: pypdf.generic
5+
:members:
6+
:undoc-members:
7+
:show-inheritance:
8+
:exclude-members: Destination, Field, Fit, RectangleObject
9+
10+
.. autoclass:: pypdf._protocols.PdfObjectProtocol
11+
:members:
12+
:undoc-members:
13+
:show-inheritance:
14+
15+
16+
.. autoclass:: pypdf._protocols.PdfReaderProtocol
17+
:members:
18+
:undoc-members:
19+
:show-inheritance:
20+
21+
22+
.. autoclass:: pypdf._protocols.PdfWriterProtocol
23+
:members:
24+
:undoc-members:
25+
:show-inheritance:

‎pypdf/_page.py

+2-2
Original file line numberDiff line numberDiff line change
@@ -303,8 +303,8 @@ class PageObject(DictionaryObject):
303303
"""
304304
PageObject represents a single page within a PDF file.
305305
306-
Typically this object will be created by accessing the
307-
:meth:`get_page()<pypdf.PdfReader.get_page>` method of the
306+
Typically these objects will be created by accessing the
307+
:attr:`pages<pypdf.PdfReader.pages>` property of the
308308
:class:`PdfReader<pypdf.PdfReader>` class, but it is
309309
also possible to create an empty page with the
310310
:meth:`create_blank_page()<pypdf._page.PageObject.create_blank_page>` static method.

‎pypdf/_reader.py

+2-1
Original file line numberDiff line numberDiff line change
@@ -298,6 +298,7 @@ def __init__(
298298
) -> None:
299299
self.strict = strict
300300
self.flattened_pages: Optional[List[PageObject]] = None
301+
#: Storage of parsed PDF objects.
301302
self.resolved_objects: Dict[Tuple[Any, Any], Optional[PdfObject]] = {}
302303
self.xref_index = 0
303304
self._page_id2num: Optional[
@@ -962,7 +963,7 @@ def _build_outline_item(self, node: DictionaryObject) -> Optional[Destination]:
962963

963964
@property
964965
def pages(self) -> List[PageObject]:
965-
"""Read-only property that emulates a list of :py:class:`Page<pypdf._page.Page>` objects."""
966+
"""Read-only property that emulates a list of :py:class:`PageObject<pypdf._page.PageObject>` objects."""
966967
return _VirtualList(self._get_num_pages, self._get_page) # type: ignore
967968

968969
@property

‎pypdf/_utils.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -537,7 +537,7 @@ def replace(self, new_image: Any, **kwargs: Any) -> None:
537537
Replace the Image with a new PIL image.
538538
539539
Args:
540-
new_image (Image.Image): The new PIL image to replace the existing image.
540+
new_image (PIL.Image.Image): The new PIL image to replace the existing image.
541541
**kwargs: Additional keyword arguments to pass to `Image.Image.save()`.
542542
543543
Raises:

‎pypdf/_writer.py

+11-9
Original file line numberDiff line numberDiff line change
@@ -1049,7 +1049,7 @@ def generate_file_identifiers(self) -> None:
10491049
When a file is first written, both identifiers shall be set to the same value.
10501050
If both identifiers match when a file reference is resolved, it is very
10511051
likely that the correct and unchanged file has been found. If only the first
1052-
identifier matches, a different version of the correct file has been found.
1052+
identifier matches, a different version of the correct file has been found.
10531053
see 14.4 "File Identifiers".
10541054
"""
10551055
if self._ID:
@@ -2792,14 +2792,16 @@ def set_page_label(
27922792
Args:
27932793
page_index_from: page index of the beginning of the range starting from 0
27942794
page_index_to: page index of the beginning of the range starting from 0
2795-
style: The numbering style to be used for the numeric portion of each page label:
2796-
'/D' Decimal arabic numerals
2797-
'/R' Uppercase roman numerals
2798-
'/r' Lowercase roman numerals
2799-
'/A' Uppercase letters (A to Z for the first 26 pages,
2800-
AA to ZZ for the next 26, and so on)
2801-
'/a' Lowercase letters (a to z for the first 26 pages,
2802-
aa to zz for the next 26, and so on)
2795+
style: The numbering style to be used for the numeric portion of each page label:
2796+
2797+
* ``/D`` Decimal arabic numerals
2798+
* ``/R`` Uppercase roman numerals
2799+
* ``/r`` Lowercase roman numerals
2800+
* ``/A`` Uppercase letters (A to Z for the first 26 pages,
2801+
AA to ZZ for the next 26, and so on)
2802+
* ``/a`` Lowercase letters (a to z for the first 26 pages,
2803+
aa to zz for the next 26, and so on)
2804+
28032805
prefix: The label prefix for page labels in this range.
28042806
start: The value of the numeric portion for the first page label
28052807
in the range.

‎pypdf/generic/_base.py

+13-14
Original file line numberDiff line numberDiff line change
@@ -73,22 +73,21 @@ def clone(
7373
ignore_fields: Optional[Sequence[Union[str, int]]] = (),
7474
) -> "PdfObject":
7575
"""
76-
clone object into pdf_dest (PdfWriterProtocol which is an interface for PdfWriter)
77-
force_duplicate: in standard if the object has been already cloned and reference,
78-
the copy is returned; when force_duplicate == True,
79-
a new copy is always performed
80-
ignore_fields : list/tuple of Fields names (for dictionaries that will
81-
be ignored during cloning (apply also to childs duplication)
82-
if fields are to be considered for a limited number of levels
83-
you have to add it as integer:
84-
eg [1,"/B","/TOTO"] means "/B" will be ignored at first level only
85-
but "/TOTO" on all levels
86-
in standard, clone function call _reference_clone (see _reference)
76+
Clone object into pdf_dest (PdfWriterProtocol which is an interface for PdfWriter).
77+
78+
By default, this method will call ``_reference_clone`` (see ``_reference``).
79+
8780
8881
Args:
89-
pdf_dest:
90-
force_duplicate: (Default value = False)
91-
ignore_fields:
82+
pdf_dest: Target to clone to.
83+
force_duplicate: By default, if the object has already been cloned and referenced,
84+
the copy will be returned; when ``True``, a new copy will be created.
85+
(Default value = ``False``)
86+
ignore_fields: List/tuple of field names (for dictionaries) that will be ignored
87+
during cloning (applies to children duplication as well). If fields are to be
88+
considered for a limited number of levels, you have to add it as integer, for
89+
example ``[1,"/B","/TOTO"]`` means that ``"/B"`` will be ignored at the first
90+
level only but ``"/TOTO"`` on all levels.
9291
9392
Returns:
9493
The cloned PdfObject

0 commit comments

Comments
 (0)