Documenting compatibility between PyFPDF & fpdf2

docs/History.md

@@ -1,10 +1,6 @@
 # History #
 
-This project, `fpdf2` is a _fork_ of the `PyFPDF` project, which can be found
-[on GitHub at reingart/pyfpdf](https://github.com/reingart/pyfpdf)
-but has been inactive since January of 2018.
-
-On 2023/08/04, `fpdf2` moved to the `py-pdf` organization: https://github.com/py-pdf/fpdf2. The context for this move can be found there: https://github.com/py-pdf/fpdf2/discussions/752. On this date, the `PyFPDF` GitHub organization has been **archived**.
+This project, `fpdf2` is a _fork_ of the `PyFPDF` project, which can still be found [on GitHub at reingart/pyfpdf](https://github.com/reingart/pyfpdf), but has been totally inactive since January 2018, and has not seen any new release since 2015.
 
 About the original `PyFPDF` lib:
 
@@ -13,13 +9,49 @@ About the original `PyFPDF` lib:
 > Later, code for native reading TTF fonts was added.
 > The project aim is to keep the library up to date, to fulfill the goals of its
 > [original roadmap](https://github.com/reingart/pyfpdf/wiki/Roadmap) and provide
-> a general overhaul of the codebase to address technical debt keeping features from being added
-> and bugs to be eradicated.
+> a general overhaul of the codebase to address technical debt keeping features from being added and bugs to be eradicated.
 > Until 2015 the code was developed at [Google Code](https://code.google.com/p/pyfpdf/):
 > 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).
 
-As of version [2.5.4](https://github.com/py-pdf/fpdf2/blob/master/CHANGELOG.md),
-`fpdf2` is fully backward compatible with PyFPDF, with the exception of one minor point:
-for the [`cell()` method](fpdf/fpdf.html#fpdf.fpdf.FPDF.cell), the default value of `h` has changed.
-It used to be `0` and is now set to the current value of `FPDF.font_size`.
+## How fpdf2 came to be ##
+
+During the spring of 2016, David Ankin (`@alexanderankin`) started a fork of PyFPDF, and added the first commit of what became `fpdf2`:
+[bd608e4](https://github.com/py-pdf/fpdf2/commits/master?after=1db5f7fdc93eac981c8f1d15856649b68e523ec8+69&branch=master&qualified_name=refs%2Fheads%2Fmaster).
+On May of 2017, the first release of `fpdf2` was published on Pypi:
+[v2.0.0](https://pypi.org/project/fpdf2/#history).
+
+On 2020, the first PRs were merged from external contributors.
+At the end of the year, Lucas Cimon (`@Lucas-C`) started contributing several improvements.
+[Version **2.1.0** was released](https://github.com/py-pdf/fpdf2/blob/master/CHANGELOG.md#210---2020-12-07) and soon after `@Lucas-C` became another maintainer of the project.
+
+On 2023/08/04, `fpdf2` moved to the `py-pdf` organization: <https://github.com/py-pdf/fpdf2>. The context for this move can be found there: <https://github.com/py-pdf/fpdf2/discussions/752>. On this date, the `PyFPDF` GitHub organization has been **archived**.
+
+## Compatibility between PyFPDF & fpdf2 ##
+
+`fpdf2` aims to be fully compatible with PyFPDF code.
+
+The notable exceptions are:
+
+* for the [`cell()` method](fpdf/fpdf.html#fpdf.fpdf.FPDF.cell), the default value of `h` has changed. It used to be `0` and is now set to the current value of `FPDF.font_size`
+* the font caching mechanism, that used the `pickle` module, has been **removed**, for security reasons, and because it provided little performance gain, and only for specific use cases - _cf._ [issue #345](https://github.com/py-pdf/fpdf2/issues/345).
+* [Template](https://py-pdf.github.io/fpdf2/fpdf/template.html#fpdf.template.Template) elements now have a **transparent background** by default, instead of white
+
+Some features are also **deprecated**. As of version 2.7.5 they **still work** but **generate a warning** when used:
+
+* ⚠️ [FPDF.rotate()](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.rotate) can produce malformed PDFs: use [FPDF.rotation()](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.rotation) instead
+* [FPDF.set_doc_option()](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.set_doc_option): simply set the `.core_fonts_encoding` property as a replacement
+* [FPDF.dashed_line()](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.dashed_line): use [FPDF.set_dash_pattern()](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.set_dash_pattern) and the normal drawing operations instead
+* the `font_cache_dir` parameter of [FPDF() constructor](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF), that is currently ignored
+* the `uni` parameter of [FPDF.add_font()](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.add_font), that is currently ignored: if the value of the `fname` argument passed to `add_font()` ends with `.ttf`, it is considered a TrueType font
+* the `type` parameter of [FPDF.image()](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.image), that is currently ignored
+* the `dest` parameter of [FPDF.output()](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.output), that is currently ignored
+* the `ln` parameter of [FPDF.multi_cell()](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.multi_cell): use `new_x=` & `new_y=` instead
+* the `split_only` parameter of [FPDF.multi_cell()](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.multi_cell): use `dry_run=True` and `output="LINES"` instead
+* the [HTMLMixin class](https://py-pdf.github.io/fpdf2/fpdf/html.html#fpdf.html.HTMLMixin): you can now directly use the [FPDF.write_html()](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.write_html) method
+* the `infile` parametyer of [Template() constructor](https://py-pdf.github.io/fpdf2/fpdf/template.html#fpdf.template.Template), that is currently ignored
+* the parameters `x/y/w/h` of `code39` elements provided to the [`Template` system](https://py-pdf.github.io/fpdf2/fpdf/template.html#fpdf.template.Template): please use `x1/y1/y2/size` instead
+* the `dest` parameter of [Template.render()](https://py-pdf.github.io/fpdf2/fpdf/template.html#fpdf.template.Template.render), that is currently ignored
+
+Note that `DeprecationWarning` messages are not displayed by Python by default.
+To get warned about deprecated features used in your code, you must execute your scripts with the `-Wd` option (_cf._ [documentation](https://docs.python.org/3/using/cmdline.html#cmdoption-W)), or enable them programmatically with `warnings.simplefilter('default', DeprecationWarning)`.

docs/index.md

@@ -99,6 +99,7 @@ or [open a discussion](https://github.com/py-pdf/fpdf2/discussions).
 
 ### They use fpdf2 ###
 <!-- cf. Watchman Pypi & DavHau/pypi-deps-db -->
+* **Harvard University** uses `fpdf2` in their [CS50 introductory class](https://cs50.harvard.edu/python/2022/psets/8/shirtificate/)
 * [Undying Dusk](https://lucas-c.itch.io/undying-dusk) : a **video game in PDF format**, with a gameplay based on exploration and logic puzzles, in the tradition of dungeon crawlers
 * [OpenDroneMap](https://github.com/OpenDroneMap/ODM) : a command line toolkit for processing aerial drone imagery
 * [OpenSfM](https://github.com/mapillary/OpenSfM) : a Structure from Motion library, serving as a processing pipeline for reconstructing camera poses and 3D scenes from multiple images

fpdf/fpdf.py

@@ -1193,15 +1193,12 @@ def set_dash_pattern(self, dash=0, gap=0, phase=0):
         Set the current dash pattern for lines and curves.
 
         Args:
-            dash (float >= 0):
-                The length of the dashes in current units.
+            dash (float >= 0): The length of the dashes in current units.
 
-            gap (float >= 0):
-                The length of the gaps between dashes in current units.
+            gap (float >= 0): The length of the gaps between dashes in current units.
                 If omitted, the dash length will be used.
 
-            phase (float >= 0):
-                Where in the sequence to start drawing.
+            phase (float >= 0): Where in the sequence to start drawing.
 
         Omitting 'dash' (= 0) resets the pattern to a solid line.
         """
@@ -1337,7 +1334,6 @@ def rect(self, x, y, w, h, style=None, round_corners=False, corner_radius=0):
             y (float): Ordinate of upper-left bounding box.
             w (float): Width.
             h (float): Height.
-
             style (fpdf.enums.RenderStyle, str): Optional style of rendering. Possible values are:
 
             * `D` or empty string: draw border. This is the default value.

fpdf/html.py

@@ -720,6 +720,11 @@ def whitespace_repl(matchobj):
 
 
 class HTMLMixin:
+    """
+    [**DEPRECATED since v2.6.0**]
+    You can now directly use the `FPDF.write_html()` method
+    """
+
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
         warnings.warn(

fpdf/template.py

@@ -32,13 +32,9 @@ class FlexTemplate:
 
     def __init__(self, pdf, elements=None):
         """
-        Arguments:
-
-            pdf (fpdf.FPDF() instance):
-                All content will be added to this object.
+        Arguments: pdf (fpdf.FPDF() instance): All content will be added to this object.
 
-            elements (list of dicts):
-                A template definition in a list of dicts.
+            elements (list of dicts): A template definition in a list of dicts.
                 If you omit this, then you need to call either load_elements()
                 or parse_csv() before doing anything else.
         """
@@ -66,8 +62,7 @@ def load_elements(self, elements):
 
         Arguments:
 
-            elements (list of dicts):
-                A template definition in a list of dicts
+            elements (list of dicts): A template definition in a list of dicts
         """
         key_config = {
             # key: type
@@ -158,21 +153,16 @@ def parse_csv(self, infile, delimiter=",", decimal_sep=".", encoding=None):
 
         Arguments:
 
-            infile (string):
-                The filename of the CSV file.
+            infile (string): The filename of the CSV file.
 
-            delimiter (single character):
-                The character that seperates the fields in the CSV file:
+            delimiter (single character): The character that seperates the fields in the CSV file:
                 Usually a comma, semicolon, or tab.
 
-            decimal_sep (single character):
-                The decimal separator used in the file.
+            decimal_sep (single character): The decimal separator used in the file.
                 Usually either a point or a comma.
 
-            encoding (string):
-                The character encoding of the file.
+            encoding (string): The character encoding of the file.
                 Default is the system default encoding.
-
         """
 
         def _varsep_float(s, default="0"):
@@ -269,11 +259,9 @@ def split_multicell(self, text, element_name):
 
         Arguments:
 
-            text (string):
-                The input text string.
+            text (string): The input text string.
 
-            element_name (string):
-                The name of the template element to fit the text inside.
+            element_name (string): The name of the template element to fit the text inside.
 
         Returns:
             A list of substrings, each of which will fit into the element width
@@ -539,14 +527,11 @@ def render(self, offsetx=0.0, offsety=0.0, rotate=0.0, scale=1.0):
 
         Arguments:
 
-            offsetx, offsety (float):
-                Place the template to move its origin to the given coordinates.
+            offsetx, offsety (float): Place the template to move its origin to the given coordinates.
 
-            rotate (float):
-                Rotate the inserted template around its (offset) origin.
+            rotate (float): Rotate the inserted template around its (offset) origin.
 
-            scale (float):
-                Scale the inserted template by this factor.
+            scale (float): Scale the inserted template by this factor.
         """
         sorted_elements = sorted(self.elements, key=lambda x: x["priority"])
         with self.pdf.local_context():
@@ -607,23 +592,18 @@ def __init__(
         """
         Arguments:
 
-            infile (str):
-                [**DEPRECATED since 2.2.0**] unused, will be removed in a later version
+            infile (str): [**DEPRECATED since 2.2.0**] unused, will be removed in a later version
 
-            elements (list of dicts):
-                A template definition in a list of dicts.
+            elements (list of dicts): A template definition in a list of dicts.
                 If you omit this, then you need to call either load_elements()
                 or parse_csv() before doing anything else.
 
-            format (str):
-                The page format of the document (eg. "A4" or "letter").
+            format (str): The page format of the document (eg. "A4" or "letter").
 
-            orientation (str):
-                The orientation of the document.
+            orientation (str): The orientation of the document.
                 Possible values are "portrait"/"P" or "landscape"/"L"
 
-            unit (str):
-                The units used in the template definition.
+            unit (str): The units used in the template definition.
                 One of "mm", "cm", "in", "pt", or a number for points per unit.
 
             title (str): The title of the document.
@@ -674,12 +654,10 @@ def render(self, outfile=None, dest=None):
 
         Arguments:
 
-            outfile (str):
-                If given, the PDF file will be written to this file name.
+            outfile (str): If given, the PDF file will be written to this file name.
                 Alternatively, the `.pdf.output()` method can be manually called.
 
-            dest (str):
-                [**DEPRECATED since 2.2.0**] unused, will be removed in a later version.
+            dest (str): [**DEPRECATED since 2.2.0**] unused, will be removed in a later version.
         """
         if dest:
             warnings.warn(

mkdocs.yml

@@ -51,8 +51,7 @@ markdown_extensions:
 plugins:
   - search
   - include-markdown
-  # Disabled while waiting for resolution of https://github.com/greenape/mknotebooks/issues/1100
-  # - mknotebooks
+  - mknotebooks
   - minify:
       minify_html: true
   - redirects: