From 6d0e8e6d06db9e3e75675f1b71fd1acde53896b5 Mon Sep 17 00:00:00 2001 From: Jamie Lemon Date: Mon, 12 Dec 2022 16:18:48 +0000 Subject: [PATCH] Adds header & footer to documentation - The header contains raw HTML which displays a link to our Discord chat service. - The footer is required to reference the SVG asset which the HTML requires (see note therein) - Additionally, if we require to render content in a footer at some point then we will have a code stub for it. --- docs/_static/custom.css | 22 +++++++++++++++++++ docs/algebra.rst | 3 +++ docs/annot.rst | 3 +++ docs/app1.rst | 4 ++++ docs/app2.rst | 4 ++++ docs/app3.rst | 4 ++++ docs/archive-class.rst | 6 ++++- docs/changes.rst | 4 ++++ docs/classes.rst | 4 ++++ docs/colors.rst | 4 ++++ docs/colorspace.rst | 4 ++++ docs/coop_low.rst | 3 +++ docs/device.rst | 4 ++++ docs/displaylist.rst | 5 +++++ docs/document-writer-class.rst | 4 ++++ docs/document.rst | 4 ++++ docs/faq.rst | 3 +++ docs/font.rst | 4 ++++ docs/footer.rst | 9 ++++++++ docs/functions.rst | 4 ++++ docs/glossary.rst | 4 ++++ docs/header.rst | 3 +++ docs/identity.rst | 4 ++++ docs/images/discord-mark-blue.svg | 1 + docs/installation.rst | 4 ++++ docs/intro.rst | 6 ++++- docs/irect.rst | 4 ++++ docs/link.rst | 4 ++++ docs/linkdest.rst | 4 ++++ docs/lowlevel.rst | 4 ++++ docs/matrix.rst | 3 +++ docs/module.rst | 4 ++++ docs/outline.rst | 4 ++++ docs/page.rst | 4 ++++ docs/pixmap.rst | 4 ++++ docs/point.rst | 3 +++ docs/quad.rst | 4 ++++ docs/recipes-annotations.rst | 3 +++ ...ipes-common-issues-and-their-solutions.rst | 6 ++++- docs/recipes-drawing-and-graphics.rst | 3 +++ docs/recipes-general.rst | 3 +++ docs/recipes-images.rst | 4 ++++ docs/recipes-journalling.rst | 4 ++++ docs/recipes-low-level-interfaces.rst | 4 ++++ docs/recipes-multiprocessing.rst | 4 ++++ docs/recipes-stories.rst | 4 +++- docs/recipes-text.rst | 4 ++++ docs/recipes.rst | 4 ++++ docs/rect.rst | 3 +++ docs/shape.rst | 4 ++++ docs/story-class.rst | 3 +++ docs/textpage.rst | 4 ++++ docs/textwriter.rst | 4 ++++ docs/toc.rst | 4 ++++ docs/tools.rst | 4 ++++ docs/tutorial.rst | 4 +++- docs/vars.rst | 4 ++++ docs/widget.rst | 4 ++++ docs/xml-class.rst | 4 +++- docs/znames.rst | 4 ++++ 60 files changed, 249 insertions(+), 6 deletions(-) create mode 100644 docs/footer.rst create mode 100644 docs/header.rst create mode 100644 docs/images/discord-mark-blue.svg diff --git a/docs/_static/custom.css b/docs/_static/custom.css index d7da22411..1369422ff 100644 --- a/docs/_static/custom.css +++ b/docs/_static/custom.css @@ -32,6 +32,24 @@ border: 1px solid #222; } +.discordLink { + display:flex; + justify-content:flex-end; + margin:0; + padding:0; + font-size: 13px; +} + +.discordLink a { + color: #000; +} + +.discordLink img { + width: 30px; + height: 30px; + margin-left: 8px; +} + /* Dark mode colors */ @media (prefers-color-scheme: dark) { @@ -65,4 +83,8 @@ color: #000; } + .discordLink a { + color: #fff; + } + } diff --git a/docs/algebra.rst b/docs/algebra.rst index 67ab6a9f3..0bbf93e24 100644 --- a/docs/algebra.rst +++ b/docs/algebra.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _Algebra: Operator Algebra for Geometry Objects @@ -204,3 +206,4 @@ Here is an example for creating the smallest rectangle enclosing given points:: True >>> +.. include:: footer.rst \ No newline at end of file diff --git a/docs/annot.rst b/docs/annot.rst index 7e1c0ee2a..e0ee3691e 100644 --- a/docs/annot.rst +++ b/docs/annot.rst @@ -1,3 +1,4 @@ +.. include:: header.rst .. _Annot: @@ -586,3 +587,5 @@ This is how the circle annotation looks like before and after the change (pop-up .. rubric:: Footnotes .. [#f1] Rotating an annotation also changes its rectangle. Depending on how the annotation was defined, the original rectangle is **not reconstructible** by setting the rotation value to zero again and will be lost. + +.. include:: footer.rst diff --git a/docs/app1.rst b/docs/app1.rst index 500e571e0..e97cc1ac8 100644 --- a/docs/app1.rst +++ b/docs/app1.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _Appendix1: ====================================== @@ -343,3 +345,5 @@ RAWDICT 4.50 **binary** images, **char** level text, layout and font details As mentioned: when excluding image extraction (last column), the relative speeds are changing drastically: except RAWDICT and XML, the other methods are almost equally fast, and RAWDICT requires 40% less execution time than the **now slowest XML**. Look at chapter **Appendix 1** for more performance information. + +.. include:: footer.rst diff --git a/docs/app2.rst b/docs/app2.rst index 31b0c97fc..30a0849ed 100644 --- a/docs/app2.rst +++ b/docs/app2.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _Appendix2: ================================================ @@ -31,3 +33,5 @@ PyMuPDF Support We continue to support the full old API with respect to embedded files -- with only minor, cosmetic changes. There even also is a new function, which delivers a list of all names under which embedded data are resgistered in a PDF, :meth:`Document.embfile_names`. + +.. include:: footer.rst diff --git a/docs/app3.rst b/docs/app3.rst index 186d87ed1..8f7bada32 100644 --- a/docs/app3.rst +++ b/docs/app3.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _Appendix3: ================================================ @@ -298,3 +300,5 @@ PyMuPDF will put error messages to *sys.stderr* prefixed with the string "mupdf: 1. The target PDF is not new / empty: grafting does not check for resources that already existed (e.g. images, fonts) in the target document before opening it. 2. Using :meth:`Page.show_pdf_page` for more than one source document: each grafting occurs **within one source** PDF only, not across multiple. So if e.g. the same image exists in pages from different source PDFs, then this will not be detected until garbage collection. + +.. include:: footer.rst diff --git a/docs/archive-class.rst b/docs/archive-class.rst index 4afa6a124..20fd0453f 100644 --- a/docs/archive-class.rst +++ b/docs/archive-class.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _Archive: ================ @@ -96,4 +98,6 @@ In PyMuPDF, archives are currently only used by :ref:`Story` objects to specify {'entries': ['310', '311', '37', '38', '39', 'pypy'], 'fmt': 'dir', 'path': 'mypath'}] - >>> \ No newline at end of file + >>> + +.. include:: footer.rst diff --git a/docs/changes.rst b/docs/changes.rst index 6ff1ee32d..c6065d078 100644 --- a/docs/changes.rst +++ b/docs/changes.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + Change Log ========== @@ -1528,3 +1530,5 @@ Changes in version 1.9.1 compared to version 1.8.0 are the following: * Incremental saves for changes are possible now using the call pattern *doc.save(doc.name, incremental=True)*. * A PDF's metadata can now be deleted, set or changed by document method *set_metadata()*. Supports incremental saves. * A PDF's bookmarks (or table of contents) can now be deleted, set or changed with the entries of a list using document method *set_toc(list)*. Supports incremental saves. + +.. include:: footer.rst diff --git a/docs/classes.rst b/docs/classes.rst index 0f2bc5dc7..11cb44f29 100644 --- a/docs/classes.rst +++ b/docs/classes.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + ============ Classes ============ @@ -30,3 +32,5 @@ Classes tools.rst widget.rst xml-class.rst + +.. include:: footer.rst diff --git a/docs/colors.rst b/docs/colors.rst index 9b7bd5a87..70fcd3d12 100644 --- a/docs/colors.rst +++ b/docs/colors.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _ColorDatabase: ================ @@ -41,3 +43,5 @@ If you want to actually see how the many available colors look like, use scripts This is a screen print of what these files look like. .. image:: images/img-colordb.* + +.. include:: footer.rst \ No newline at end of file diff --git a/docs/colorspace.rst b/docs/colorspace.rst index 891154f2c..2e4e3e37e 100644 --- a/docs/colorspace.rst +++ b/docs/colorspace.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _Colorspace: ================ @@ -37,3 +39,5 @@ Represents the color space of a :ref:`Pixmap`. * :data:`csRGB` = *fitz.Colorspace(fitz.CS_RGB)* * :data:`csGRAY` = *fitz.Colorspace(fitz.CS_GRAY)* * :data:`csCMYK` = *fitz.Colorspace(fitz.CS_CMYK)* + +.. include:: footer.rst \ No newline at end of file diff --git a/docs/coop_low.rst b/docs/coop_low.rst index f9e3a59d0..bd9cfd5f4 100644 --- a/docs/coop_low.rst +++ b/docs/coop_low.rst @@ -1,3 +1,4 @@ +.. include:: header.rst .. _cooperation: @@ -69,3 +70,5 @@ This will save ca. 25% overall execution time for the HTML, XHTML and JSON text If you however do need images, use a value of 7 for flags: >>> flags = fitz.TEXT_PRESERVE_LIGATURES | fitz.TEXT_PRESERVE_WHITESPACE | fitz.TEXT_PRESERVE_IMAGES + +.. include:: footer.rst diff --git a/docs/device.rst b/docs/device.rst index ee668a9f1..3f264162a 100644 --- a/docs/device.rst +++ b/docs/device.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _Device: ================ @@ -28,3 +30,5 @@ The different format handlers (pdf, xps, etc.) interpret pages to a "device". De :type textpage: :ref:`TextPage` :arg int flags: control the way how text is parsed into the text page. Currently 3 options can be coded into this parameter, see :ref:`TextPreserve`. To set these options use something like *flags=0 | TEXT_PRESERVE_LIGATURES | ...*. + +.. include:: footer.rst diff --git a/docs/displaylist.rst b/docs/displaylist.rst index c89fefa27..c7ca9a454 100644 --- a/docs/displaylist.rst +++ b/docs/displaylist.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _DisplayList: ================ @@ -89,3 +91,6 @@ A display list is populated with objects from a page, usually by executing :meth Contains the display list's mediabox. This will equal the page's rectangle if it was created via :meth:`Page.get_displaylist`. :type: :ref:`Rect` + + +.. include:: footer.rst diff --git a/docs/document-writer-class.rst b/docs/document-writer-class.rst index 100783578..833bd8e78 100644 --- a/docs/document-writer-class.rst +++ b/docs/document-writer-class.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _DocumentWriter: ================ @@ -49,3 +51,5 @@ Using DocumentWriter_ also for other document types might happen in the future. Close the output file. This method is required for writing any pending data. For usage examples consult the section of :ref:`Story`. + +.. include:: footer.rst diff --git a/docs/document.rst b/docs/document.rst index 8c8739da3..d13ba2f42 100644 --- a/docs/document.rst +++ b/docs/document.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _Document: ================ @@ -2032,3 +2034,5 @@ Other Examples .. [#f6] For a *False* the **complete document** must be scanned. Both methods **do not load pages,** but only scan object definitions. This makes them at least 10 times faster than application-level loops (where total response time roughly equals the time for loading all pages). For the :ref:`AdobeManual` (756 pages) and the Pandas documentation (over 3070 pages) -- both have no annotations -- the method needs about 11 ms for the answer *False*. So response times will probably become significant only well beyond this order of magnitude. .. [#f7] This only works under certain conditions. For example, if there is normal text covered by some image on top of it, then this is undetectable and the respective text is **not** removed. Similar is true for white text on white background, and so on. + +.. include:: footer.rst diff --git a/docs/faq.rst b/docs/faq.rst index 5ada3831d..8011ecd34 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _FAQ: ============================== @@ -12,3 +14,4 @@ Please see: :ref:`Recipes: Table of Contents` +.. include:: footer.rst diff --git a/docs/font.rst b/docs/font.rst index c83e7a0b2..0bae6cf4e 100644 --- a/docs/font.rst +++ b/docs/font.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _Font: ================ @@ -360,3 +362,5 @@ A Font object also contains useful general information, like the font bbox, the .. [#f1] MuPDF does not support all fontfiles with this feature and will raise exceptions like *"mupdf: FT_New_Memory_Face((null)): unknown file format"*, if it encounters issues. The :ref:`TextWriter` methods check :attr:`Font.is_writable`. .. [#f2] The built-in module *array* has been chosen for its speed and its compact representation of values. + +.. include:: footer.rst diff --git a/docs/footer.rst b/docs/footer.rst new file mode 100644 index 000000000..84aedfe1f --- /dev/null +++ b/docs/footer.rst @@ -0,0 +1,9 @@ +.. note - this ensures that the Sphinx build system will pull in the image (as it is referenced in an RST file) to _images, + we don't want to display it via rst markup due to limitations (hence width:0), however we do want it available for our raw HTML + which we use in header.rst. + +.. image:: images/discord-mark-blue.svg + :alt: Discord logo + :width: 0 + :height: 0 + :target: https://discord.gg/TSpYGBW4eq \ No newline at end of file diff --git a/docs/functions.rst b/docs/functions.rst index 7a1110621..afb40c914 100644 --- a/docs/functions.rst +++ b/docs/functions.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + ============ Functions ============ @@ -791,3 +793,5 @@ Yet others are handy, general-purpose utilities. .. method:: EMPTY_IRECT() Return the "standard" empty and invalid rectangle ``Rect(2147483520.0, 2147483520.0, -2147483648.0, -2147483648.0)`` resp. quad. Its top-left and bottom-right point values are reversed compared to the infinite rectangle. It will e.g. be used to indicate empty bboxes in ``page.get_text("dict")`` dictionaries. There are however infinitely many empty or invalid rectangles. + +.. include:: footer.rst diff --git a/docs/glossary.rst b/docs/glossary.rst index 2cc2930dd..3e903b067 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _Glossary: ============== @@ -161,3 +163,5 @@ Glossary .. data:: ligature Some frequent character combinations are represented by their own special glyphs in more advanced fonts. Typical examples are "fi", "fl", "ffi" and "ffl". These compounds are called *ligatures*. In PyMuPDF text extractions, there is the option to either return the corresponding unicode unchanged, or split ligatures up into their constituent parts: "fi" ==> "f" + "i", etc. + +.. include:: footer.rst diff --git a/docs/header.rst b/docs/header.rst new file mode 100644 index 000000000..be2b52abb --- /dev/null +++ b/docs/header.rst @@ -0,0 +1,3 @@ +.. raw:: html + +
Find #pymupdf on DiscordDiscord logo
\ No newline at end of file diff --git a/docs/identity.rst b/docs/identity.rst index 03d8d0e9a..7e87ade68 100644 --- a/docs/identity.rst +++ b/docs/identity.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _Identity: ============ @@ -14,3 +16,5 @@ If you need a **mutable** identity matrix as a starting point, use one of the fo >>> m = fitz.Matrix(1, 1) # use scaling by factor 1 >>> m = fitz.Matrix(0) # use rotation by zero degrees >>> m = fitz.Matrix(fitz.Identity) # make a copy of Identity + +.. include:: footer.rst diff --git a/docs/images/discord-mark-blue.svg b/docs/images/discord-mark-blue.svg new file mode 100644 index 000000000..ca6540076 --- /dev/null +++ b/docs/images/discord-mark-blue.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/installation.rst b/docs/installation.rst index ad840e466..f9a11accb 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + Installation ============= @@ -141,3 +143,5 @@ So for a working OCR functionality, make sure to complete this checklist: .. rubric:: Footnotes .. [#f1] In the next MuPDF version, it will be possible to pass this value as a parameter -- directly in the OCR invocations. + +.. include:: footer.rst diff --git a/docs/intro.rst b/docs/intro.rst index df251da9c..4d5ae70b3 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + Introduction ============== @@ -57,4 +59,6 @@ Artifex, the Artifex logo, MuPDF, and the MuPDF logo are registered trademarks o .. rubric:: Footnotes -.. [#f1] PyMuPDF generally only supports Python versions that are still maintained by the Python Software Foundation. Once a Python version is being retired, PyMuPDF support will also be ended. This means that wheels for a retired Python platform will no longer be provided, and that Python language features may be used that did not exist in the retired Python version. \ No newline at end of file +.. [#f1] PyMuPDF generally only supports Python versions that are still maintained by the Python Software Foundation. Once a Python version is being retired, PyMuPDF support will also be ended. This means that wheels for a retired Python platform will no longer be provided, and that Python language features may be used that did not exist in the retired Python version. + +.. include:: footer.rst diff --git a/docs/irect.rst b/docs/irect.rst index 526029d0c..865d2cb28 100644 --- a/docs/irect.rst +++ b/docs/irect.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _IRect: ========== @@ -214,3 +216,5 @@ IRect is a rectangular bounding box, very similar to :ref:`Rect`, except that al * This class adheres to the Python sequence protocol, so components can be accessed via their index, too. Also refer to :ref:`SequenceTypes`. * Rectangles can be used with arithmetic operators -- see chapter :ref:`Algebra`. +.. include:: footer.rst + diff --git a/docs/link.rst b/docs/link.rst index ba99deca2..cd5b74d3e 100644 --- a/docs/link.rst +++ b/docs/link.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _Link: ================ @@ -118,3 +120,5 @@ There is a parent-child relationship between a link and its page. If the page ob The link destination details object. :type: :ref:`linkDest` + +.. include:: footer.rst diff --git a/docs/linkdest.rst b/docs/linkdest.rst index d8582c946..e13d7296d 100644 --- a/docs/linkdest.rst +++ b/docs/linkdest.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _linkDest: ================ @@ -99,3 +101,5 @@ Class representing the `dest` property of an outline entry or a link. Describes The name of the URI this destination points to. :type: str + +.. include:: footer.rst diff --git a/docs/lowlevel.rst b/docs/lowlevel.rst index 0db7cdc64..b2c12499b 100644 --- a/docs/lowlevel.rst +++ b/docs/lowlevel.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + ================================= Low Level Functions and Classes ================================= @@ -9,3 +11,5 @@ Contains a number of functions and classes for the experienced user. To be used functions device coop_low + +.. include:: footer.rst diff --git a/docs/matrix.rst b/docs/matrix.rst index 79332261b..4c4c879b0 100644 --- a/docs/matrix.rst +++ b/docs/matrix.rst @@ -1,3 +1,4 @@ +.. include:: header.rst .. _Matrix: @@ -235,3 +236,5 @@ Rotating Finally a rotation by 30 clockwise degrees (*prerotate(-30)*). |rot60| + +.. include:: footer.rst diff --git a/docs/module.rst b/docs/module.rst index 001fc8fac..ec7792cf9 100644 --- a/docs/module.rst +++ b/docs/module.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _Module: ============================ @@ -477,3 +479,5 @@ Command:: .. highlight:: python + +.. include:: footer.rst diff --git a/docs/outline.rst b/docs/outline.rst index 1f8b16c7c..100dea47a 100644 --- a/docs/outline.rst +++ b/docs/outline.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _Outline: ================ @@ -70,3 +72,5 @@ Outline The link destination details object. :type: :ref:`linkDest` + +.. include:: footer.rst diff --git a/docs/page.rst b/docs/page.rst index 311cb82b1..54936197c 100644 --- a/docs/page.rst +++ b/docs/page.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _Page: ================ @@ -1751,3 +1753,5 @@ The page number "pno" is a 0-based integer ``-∞ < pno < page_count``. .. [#f7] In PDF, an area enclosed by some lines or curves can have a property called "orientation". This is significant for switching on or off the fill color of that area when there exist multiple area overlaps - see discussion in method :meth:`Shape.finish` using the "non-zero winding number" rule. While orientation of curves, quads, triangles and other shapes enclosed by lines always was detectable, this has been impossible for "re" (rectangle) items in the past. Adding the orientation parameter now delivers the missing information. .. [#f8] Hyphenation detection simply means that if the last character of a line is "-", it will be assumed to be a continuation character. That character will not be found by text searching with its default flag setting. Please take note, that a MuPDF *line* may not always be what you expect: words separated by overly large gaps (e.g. caused by text justification) may constitute seperate MuPDF lines. If then any of these words ends with a hyphen, it will only be found by text searching if hyphenation is switched off. + +.. include:: footer.rst diff --git a/docs/pixmap.rst b/docs/pixmap.rst index 1b41193c0..b644cc3ec 100644 --- a/docs/pixmap.rst +++ b/docs/pixmap.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _Pixmap: ================ @@ -645,3 +647,5 @@ psd gray, rgb, cmyk yes .psd Adobe Photoshop Document .. [#f1] If you need a **vector image** from the SVG, you must first convert it to a PDF. Try :meth:`Document.convert_to_pdf`. If this is not good enough, look for other SVG-to-PDF conversion tools like the Python packages `svglib `_, `CairoSVG `_, `Uniconvertor `_ or the Java solution `Apache Batik `_. Have a look at our Wiki for more examples. .. [#f2] To also set the alpha property, add an additional step to this method by dropping or adding an alpha channel to the result. + +.. include:: footer.rst diff --git a/docs/point.rst b/docs/point.rst index 5b5044f4f..fac454002 100644 --- a/docs/point.rst +++ b/docs/point.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _Point: ================ @@ -100,3 +102,4 @@ Point * This class adheres to the Python sequence protocol, so components can be accessed via their index, too. Also refer to :ref:`SequenceTypes`. * Rectangles can be used with arithmetic operators -- see chapter :ref:`Algebra`. +.. include:: footer.rst diff --git a/docs/quad.rst b/docs/quad.rst index 84fe9ba3e..61e78e507 100644 --- a/docs/quad.rst +++ b/docs/quad.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _Quad: ========== @@ -154,3 +156,5 @@ For a rectangle, only its top-left point belongs to it. Since v1.19.0, rectangle >>> # but: >>> rect.br in rect.quad True + +.. include:: footer.rst diff --git a/docs/recipes-annotations.rst b/docs/recipes-annotations.rst index 1f8b43dbf..3b2b6584a 100644 --- a/docs/recipes-annotations.rst +++ b/docs/recipes-annotations.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _RecipesAnnotations: ============================== @@ -146,3 +148,4 @@ This is the result: .. image:: images/img-inkannot.* :scale: 50 +.. include:: footer.rst diff --git a/docs/recipes-common-issues-and-their-solutions.rst b/docs/recipes-common-issues-and-their-solutions.rst index 2213fcb5a..25dc4fa1e 100644 --- a/docs/recipes-common-issues-and-their-solutions.rst +++ b/docs/recipes-common-issues-and-their-solutions.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _RecipesCommonIssuesAndTheirSolutions: ========================================== @@ -149,4 +151,6 @@ Cause Solution ^^^^^^^^ 1. Use layout preserving text extraction: ``python -m fitz gettext file.pdf``. -2. If other text extraction tools also don't work, then the only solution again is OCRing the page. \ No newline at end of file +2. If other text extraction tools also don't work, then the only solution again is OCRing the page. + +.. include:: footer.rst diff --git a/docs/recipes-drawing-and-graphics.rst b/docs/recipes-drawing-and-graphics.rst index 2da041397..aad7a4e40 100644 --- a/docs/recipes-drawing-and-graphics.rst +++ b/docs/recipes-drawing-and-graphics.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _RecipesDrawingAndGraphics: ============================== @@ -193,3 +195,4 @@ Here is a comparison between input and output of an example page, created by the .. note:: You can use the path list to make your own lists of e.g. all lines or all rectangles on the page and subselect them by criteria, like color or position on the page etc. +.. include:: footer.rst diff --git a/docs/recipes-general.rst b/docs/recipes-general.rst index a285c1cca..882825366 100644 --- a/docs/recipes-general.rst +++ b/docs/recipes-general.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _RecipesGeneral: ============================== @@ -509,3 +511,4 @@ To **keep the encryption method** of a PDF save it using *encryption=fitz.PDF_EN To **change the encryption method** specify the full range of options above (encryption, owner_pw, user_pw, permissions). An incremental save is **not possible** in this case. +.. include:: footer.rst diff --git a/docs/recipes-images.rst b/docs/recipes-images.rst index e01386535..75464e03d 100644 --- a/docs/recipes-images.rst +++ b/docs/recipes-images.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _RecipesImages: ============================== @@ -576,3 +578,5 @@ Basic code pattern for :meth:`Page.show_pdf_page`. Source and target PDF must be keep_proportion=True, # keep aspect ratio overlay=True, # put in foreground ) + +.. include:: footer.rst diff --git a/docs/recipes-journalling.rst b/docs/recipes-journalling.rst index ee8944dcb..58c384f56 100644 --- a/docs/recipes-journalling.rst +++ b/docs/recipes-journalling.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _RecipesJournalling: ========================================= @@ -134,3 +136,5 @@ Description: >>> # this has changed the journal: >>> # previous last 3 text line operations were removed, and >>> # we have only 4 operations: drawing the line is the new last one + +.. include:: footer.rst diff --git a/docs/recipes-low-level-interfaces.rst b/docs/recipes-low-level-interfaces.rst index 85ba83a45..e36c0036b 100644 --- a/docs/recipes-low-level-interfaces.rst +++ b/docs/recipes-low-level-interfaces.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _RecipesLowLevelInterfaces: ========================================= @@ -438,3 +440,5 @@ There also exist granular, elegant ways to access and manipulate selected PDF :d RuntimeError: path to 'F' has indirects .. caution:: These are expert functions! There are no validations as to whether valid PDF objects, xrefs, etc. are specified. As with other low-level methods there is the risk to render the PDF, or parts of it unusable. + +.. include:: footer.rst diff --git a/docs/recipes-multiprocessing.rst b/docs/recipes-multiprocessing.rst index 73185a46c..ff4ce570a 100644 --- a/docs/recipes-multiprocessing.rst +++ b/docs/recipes-multiprocessing.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _RecipesMultiprocessing: ============================== @@ -21,3 +23,5 @@ Here is a more complex example involving inter-process communication between a m .. literalinclude:: samples/multiprocess-gui.py :language: python + +.. include:: footer.rst diff --git a/docs/recipes-stories.rst b/docs/recipes-stories.rst index d73d07850..54bca6956 100644 --- a/docs/recipes-stories.rst +++ b/docs/recipes-stories.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _RecipesStories: @@ -502,7 +504,7 @@ in a PDF-specific API.] - ``float`` is unavailable. - +.. include:: footer.rst .. External Links: diff --git a/docs/recipes-text.rst b/docs/recipes-text.rst index 49beca2b2..447e05735 100644 --- a/docs/recipes-text.rst +++ b/docs/recipes-text.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _RecipesText: ============================== @@ -399,3 +401,5 @@ The snippet above indeed leads to three different copies of the Helvetica font i [6, 'n/a', 'Type1', 'Helvetica', 'helv', 'WinAnsiEncoding'] [7, 'n/a', 'Type1', 'Helvetica', 'HElv', 'WinAnsiEncoding'] [8, 'n/a', 'Type1', 'Helvetica', 'HELV', 'WinAnsiEncoding'] + +.. include:: footer.rst diff --git a/docs/recipes.rst b/docs/recipes.rst index ed660c92c..42771bedb 100644 --- a/docs/recipes.rst +++ b/docs/recipes.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _RecipesTOC: @@ -45,3 +47,5 @@ Recipes .. toctree:: recipes-stories.rst + +.. include:: footer.rst diff --git a/docs/rect.rst b/docs/rect.rst index fb05be76a..83849346d 100644 --- a/docs/rect.rst +++ b/docs/rect.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _Rect: ========== @@ -328,3 +330,4 @@ The following remarks are also valid for :ref:`IRect` objects: * This class adheres to the Python sequence protocol, so components can be accessed via their index, too. Also refer to :ref:`SequenceTypes`. * Rectangles can be used with arithmetic operators -- see chapter :ref:`Algebra`. +.. include:: footer.rst diff --git a/docs/shape.rst b/docs/shape.rst index 49e7a4e53..4151ae34b 100644 --- a/docs/shape.rst +++ b/docs/shape.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _Shape: Shape @@ -628,3 +630,5 @@ Common Parameters **closePath** (*bool*) Causes the end point of a drawing to be automatically connected with the starting point (by a straight line). + +.. include:: footer.rst diff --git a/docs/story-class.rst b/docs/story-class.rst index 347b17203..2aeb4952b 100644 --- a/docs/story-class.rst +++ b/docs/story-class.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _Story: ================ @@ -282,3 +284,4 @@ The parameter passed to the ``recorder`` function is an object with the followin * ``elpos.page_num`` (int) -- page number; only present when using `fitz.Story.write*()` functions. +.. include:: footer.rst diff --git a/docs/textpage.rst b/docs/textpage.rst index c991aca0a..fca59ef26 100644 --- a/docs/textpage.rst +++ b/docs/textpage.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _TextPage: ================ @@ -338,3 +340,5 @@ This image shows the relationship between a character's bbox and its quad: |text .. rubric:: Footnotes .. [#f1] Image specifications for a PDF page are done in a page's (sub-) :data:`dictionary`, called *"/Resources"*. Resource dictionaries can be **inherited** from the page's parent object (usually the :data:`catalog`). The PDF creator may e.g. define one */Resources* on file level, naming all images and all fonts ever used by any page. In these cases, :meth:`Page.get_images` and :meth:`Page.get_fonts` will return the same lists for all pages. + +.. include:: footer.rst diff --git a/docs/textwriter.rst b/docs/textwriter.rst index 5959d1abf..9c7f01344 100644 --- a/docs/textwriter.rst +++ b/docs/textwriter.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _TextWriter: ================ @@ -188,3 +190,5 @@ Using this object entails three steps: 4. Font and fontsize can freely vary within the same TextWriter. This can be used to let text with different properties appear on the same displayed line: just specify *pos* accordingly, and e.g. set it to :attr:`last_point` of the previously added item. 5. You can use the *pos* argument of :meth:`TextWriter.fill_textbox` to set the position of the first text character. This allows filling the same textbox with contents from different :ref:`TextWriter` objects, thus allowing for multiple colors, opacities, etc. 6. MuPDF does not support all fonts with this feature, e.g. no Type3 fonts. Starting with v1.18.0 this can be checked via the font attribute :attr:`Font.is_writable`. This attribute is also checked when using :ref:`TextWriter` methods. + +.. include:: footer.rst diff --git a/docs/toc.rst b/docs/toc.rst index b8d2e4d4e..fa943a9f7 100644 --- a/docs/toc.rst +++ b/docs/toc.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + **PyMuPDF Documentation** ================================= @@ -20,3 +22,5 @@ app3.rst changes.rst znames.rst + +.. include:: footer.rst diff --git a/docs/tools.rst b/docs/tools.rst index c9332621c..3b426bf90 100644 --- a/docs/tools.rst +++ b/docs/tools.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _Tools: Tools @@ -266,3 +268,5 @@ Example Session .. [#f1] This memory area is internally used by MuPDF, and it serves as a cache for objects that have already been read and interpreted, thus improving performance. The most bulky object types are images and also fonts. When an application starts up the MuPDF library (in our case this happens as part of *import fitz*), it must specify a maximum size for this area. PyMuPDF's uses the default value (256 MB) to limit memory consumption. Use the methods here to control or investigate store usage. For example: even after a document has been closed and all related objects have been deleted, the store usage may still not drop down to zero. So you might want to enforce that before opening another document. .. [#f2] By default PyMuPDF and MuPDF use ``malloc()``/``free()`` for dynamic memory management. One can instead force them to use the Python allocation functions ``PyMem_New()``/``PyMem_Del()``, by modifying *fitz/fitz.i* to do ``#define JM_MEMORY 1`` and rebuilding PyMuPDF. + +.. include:: footer.rst diff --git a/docs/tutorial.rst b/docs/tutorial.rst index 6c7907dc5..269f1a233 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _Tutorial: ========= @@ -397,7 +399,7 @@ This document also contains a :ref:`FAQ`. This chapter has close connection to t .. [#f3] "Sequences" are Python objects conforming to the sequence protocol. These objects implement a method named *__getitem__()*. Best known examples are Python tuples and lists. But *array.array*, *numpy.array* and PyMuPDF's "geometry" objects (:ref:`Algebra`) are sequences, too. Refer to :ref:`SequenceTypes` for details. - +.. include:: footer.rst .. External links: diff --git a/docs/vars.rst b/docs/vars.rst index bcbd48e97..48e76b588 100644 --- a/docs/vars.rst +++ b/docs/vars.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + =============================== Constants and Enumerations =============================== @@ -483,3 +485,5 @@ MuPDF has defined the following icons for **rubber stamp** annotations:: STAMP_Sold 11 STAMP_TopSecret 12 STAMP_Draft 13 + +.. include:: footer.rst diff --git a/docs/widget.rst b/docs/widget.rst index 4df5c3484..d44e968ef 100644 --- a/docs/widget.rst +++ b/docs/widget.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _Widget: ================ @@ -202,3 +204,5 @@ PyMuPDF supports the creation and update of many, but not all widget types. .. rubric:: Footnotes .. [#f1] If you intend to re-access a new or updated field (e.g. for making a pixmap), make sure to reload the page first. Either close and re-open the document, or load another page first, or simply do ``page = doc.reload_page(page)``. + +.. include:: footer.rst diff --git a/docs/xml-class.rst b/docs/xml-class.rst index 491d8b86c..84b02477a 100644 --- a/docs/xml-class.rst +++ b/docs/xml-class.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _Xml: ================ @@ -422,7 +424,7 @@ Methods that are flagged as "context managers" can conveniently be used in this para.set_italic(False).set_bold(False).add_text("regular text") para.add_text("more regular text") - +.. include:: footer.rst .. External links: diff --git a/docs/znames.rst b/docs/znames.rst index 98b5b14f7..d4b0f9f68 100644 --- a/docs/znames.rst +++ b/docs/znames.rst @@ -1,3 +1,5 @@ +.. include:: header.rst + .. _Deprecated: ================ @@ -41,3 +43,5 @@ Deprecated names are not separately documented. The following list will help you .. note:: This is automatically generated. One or two items refer to yet undocumented methods - please simply ignore them. .. include:: deprecated.rst + +.. include:: footer.rst