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.
pymupdf · Dec 12, 2022 · 6d0e8e6 · 6d0e8e6
1 parent 3aee308
commit 6d0e8e6
Show file tree

Hide file tree

Showing 60 changed files with 249 additions and 6 deletions.
diff --git 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
@@ -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
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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'}]
-      >>> 
+      >>> 
+
+.. include:: footer.rst
diff --git 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
@@ -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
@@ -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
diff --git 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
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -1,3 +1,5 @@
+.. include:: header.rst
+
 .. _FAQ:
 
 ==============================
@@ -12,3 +14,4 @@ Please see:
 :ref:`Recipes: Table of Contents<RecipesTOC>`
 
 
+.. include:: footer.rst
diff --git 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
@@ -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
diff --git 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
@@ -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
@@ -0,0 +1,3 @@
+.. raw:: html
+
+    <div class="discordLink"><a href="https://discord.gg/TSpYGBW4eq" target=_blank>Find <b>#pymupdf</b> on <b>Discord</b><img src="_images/discord-mark-blue.svg" alt="Discord logo" /></a></div>
diff --git 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
diff --git 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
@@ -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.
+.. [#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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -1,3 +1,5 @@
+.. include:: header.rst
+
 .. _Module:
 
 ============================
@@ -477,3 +479,5 @@ Command::
 
 
 .. highlight:: python
+
+.. include:: footer.rst