diff --git a/docs/Development.md b/docs/Development.md index eedd5278a..90280d648 100644 --- a/docs/Development.md +++ b/docs/Development.md @@ -131,21 +131,15 @@ In order to generate a "reference" PDF file, simply call `assert_pdf_equal` once with `generate=True`. ```python -import fpdf - -svg = fpdf.svg.SVGObject.from_file("path/to/file.svg") -pdf = fpdf.FPDF(unit="pt", format=(svg.width, svg.height)) -pdf.add_page() -svg.draw_to_page(pdf) - -assert_pdf_equal( - pdf, - "path/for/pdf/output.pdf", - "path/for/pdf/", - generate=True -) +def test_some_feature(tmp_path): + pdf = FPDF() + pdf.add_page() + pdf.rect(10, 10, 60, 80) + assert_pdf_equal(pdf, HERE / "some_feature.pdf", tmp_path, generate=True) ``` +Next you can invoke `pytest path/to/test.py` to generate the file `some_feature.pdf`. + ### Visually comparing all PDF reference files modified on a branch This script will build an serve a single HTML page containing all PDF references file modified on your current `git` branch, @@ -252,13 +246,14 @@ To preview the API documentation, launch a local rendering server with: The **PDF 1.7 spec** is available on Adobe website: [PDF32000_2008.pdf](https://opensource.adobe.com/dc-acrobat-sdk-docs/pdfstandards/PDF32000_2008.pdf). -The **PDF 2.0 spec** is available on the [Adobe website](https://developer.adobe.com/document-services/docs/assets/5b15559b96303194340b99820d3a70fa/PDF_ISO_32000-2.pdf) or on the [PDF Association website](https://www.pdfa.org/sponsored-standards) +The **PDF 2.0 spec** is available on the [Adobe website](https://developer.adobe.com/document-services/docs/assets/5b15559b96303194340b99820d3a70fa/PDF_ISO_32000-2.pdf) or on the [PDF Association website](https://www.pdfa.org/sponsored-standards). It may be intimidating at first, but while technical, it is usually quite clear and understandable. It is also a great place to look for new features for `fpdf2`: there are still many PDF features that this library does not support. + ## Useful tools to manipulate PDFs ### qpdf @@ -273,13 +268,17 @@ qpdf --qdf doc.pdf doc-qdf.pdf This is extremely useful to peek into the PDF document structure. -### set_pdf_xref.py +### pdfly + +`pdfly` is a very handy CLI tool to manipulate PDF files: [py-pdf/pdfly](https://github.com/py-pdf/pdfly?tab=readme-ov-file#usage). -[set_pdf_xref.py](https://github.com/Lucas-C/dotfiles_and_notes/blob/master/languages/python/set_pdf_xref.py) is a small Python script that can **rebuild a PDF xref table**. +Those are some very useful commands: -This is very useful, as a PDF with an invalid xref cannot be opened. -An xref table is basically an index of the document internal sections. +* `cat`: concatenate pages from PDF files into a single PDF file +* `meta`: show metadata of a PDF file +* `x2pdf`: convert one or more files to PDF. Each file is a page. +* `update-offsets`: rebuild a PDF xref table. This is allows to manually edit a PDF file in a text editor, and then fix its xref table so that a PDF viewer will be able to open it. + +A **xref table** is basically an index of the document internal sections. When manually modifying a PDF file (for example one produced by `qpdf --qdf`), if the characters count in any of its sections changes, the xref table must be rebuilt. - -With `set_pdf_xref.py doc.pdf --inplace`, you can change some values inside any PDF file, and then quickly make it valid again to be viewed in a PDF viewer. diff --git a/docs/History.md b/docs/History.md index 76e6130d7..f591d0141 100644 --- a/docs/History.md +++ b/docs/History.md @@ -11,11 +11,11 @@ About the original `PyFPDF` lib: > Later, in the Python FPDF library, code for native reading TTF fonts was added. > In 2008 it was moved from a SVN repository to git on [Google Code](https://code.google.com/p/pyfpdf/) > by Mariano Reingart, who became the maintainer of FPDF. -> In 2013, it was migrated to GitHub: https://github.com/reingart/pyfpdf. +> In 2013, it was migrated to GitHub: . > You can still access the [old issues](https://github.com/reingart/pyfpdf_googlecode/issues), > and [old wiki](https://github.com/reingart/pyfpdf_googlecode/tree/wiki), > that were moved to a dedicated repository. -> The original roadmap can also still be found there: https://github.com/reingart/pyfpdf/wiki/Roadmap +> The original roadmap can also still be found there: ## How fpdf2 came to be ## diff --git a/docs/Patterns.md b/docs/Patterns.md index e881bdbd4..6cf91e3c0 100644 --- a/docs/Patterns.md +++ b/docs/Patterns.md @@ -1,5 +1,7 @@ # Patterns and Gradients +_New in [:octicons-tag-24: 2.8.3](https://github.com/py-pdf/fpdf2/blob/master/CHANGELOG.md)_ + ## Overview In PDF (Portable Document Format), a **pattern** is a graphical object that can be used to fill (or stroke) shapes. Patterns can include simple color fills, images, or more advanced textures and gradients. @@ -51,8 +53,9 @@ with pdf.use_pattern(linear_grad): # Draw a rectangle that will be filled with the gradient pdf.rect(x=10, y=10, w=100, h=20, style="FD") -pdf.output("linear_gradient_example.pdf") +pdf.output("pattern_linear_demo.pdf") ``` +Result: [pattern_linear_demo.pdf](./pattern_linear_demo.pdf) **Key Parameters**: @@ -76,8 +79,8 @@ pdf.add_page() # Define a radial gradient radial_grad = RadialGradient( pdf, - start_circle_x=50, # Center X of inner circle - start_circle_y=50, # Center Y of inner circle + start_circle_x=30, # Center X of inner circle + start_circle_y=30, # Center Y of inner circle start_circle_radius=0, # Radius of inner circle end_circle_x=50, # Center X of outer circle end_circle_y=50, # Center Y of outer circle @@ -89,8 +92,9 @@ with pdf.use_pattern(radial_grad): # Draw a circle filled with the radial gradient pdf.circle(x=50, y=50, radius=25, style="FD") -pdf.output("radial_gradient_example.pdf") +pdf.output("pattern_radial_demo.pdf") ``` +Result: [pattern_radial_demo.pdf](./pattern_radial_demo.pdf) **Key Parameters**: diff --git a/docs/index.md b/docs/index.md index 2fc5b4fc6..45d34e191 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,8 +12,8 @@ from fpdf import FPDF pdf = FPDF() pdf.add_page() -pdf.set_font('helvetica', size=12) -pdf.cell(text="hello world") +pdf.set_font('Helvetica', size=12) +pdf.cell(text="Hello world!") pdf.output("hello_world.pdf") ``` diff --git a/docs/pattern_linear_demo.pdf b/docs/pattern_linear_demo.pdf new file mode 100644 index 000000000..a020ab675 Binary files /dev/null and b/docs/pattern_linear_demo.pdf differ diff --git a/docs/pattern_radial_demo.pdf b/docs/pattern_radial_demo.pdf new file mode 100644 index 000000000..39fd664c4 Binary files /dev/null and b/docs/pattern_radial_demo.pdf differ diff --git a/mkdocs.yml b/mkdocs.yml index f1dcb411b..14beb561f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -190,4 +190,6 @@ extra: - icon: fontawesome/brands/github link: https://github.com/py-pdf/fpdf2 - icon: fontawesome/brands/python - link: https://pypi.org/project/fpdf2/ \ No newline at end of file + link: https://pypi.org/project/fpdf2/ + +dev_addr: 127.0.0.1:8080