Docs cleanup

docs/README.md

@@ -12,6 +12,13 @@ This README assumes you have [Sphinx v5.0.2 installed](https://www.sphinx-doc.or
 
 Within `docs` update the associated restructured text (`.rst`) files. These files represent the corresponding document pages. 
 
+### Conventions
+
+- Code parameters and referenced code objects should be referenced within backticks, not italics, double backtick is better for safety
+- When referencing names of some of our products surround with | , e.g. |PyMuPDF| , not PyMuPDF, see `header.rst` for products names listing
+- When hyperlinking, avoid inline hyperlinks and try to references link from common location at page bottom, also avoid the use of "here" or "click here" as this provides little information about the link content. e.g.
+
+"`Click here <link>` for our Story class". Should be re-written to something more like "Find out more `on our Story class <link>`"
 
 ## Building HTML documentation
 

docs/about-performance.rst

@@ -316,7 +316,7 @@
         <div class="about-graph-x-axis speed">
             <div class="segment"><i id="transP17">fastest</i></div>
             <div class="segment">&#8592;</div>
-            <div class="segment"><i id="transP18"slowest</i></div>
+            <div class="segment"><i id="transP18">slowest</i></div>
         </div>
 
     </div>

docs/about.rst

@@ -87,7 +87,7 @@ License and Copyright
 
 
 
-|PyMuPDF| and :title:`MuPDF` are now available under both, open-source :title:`AGPL` and commercial license agreements. Please read the full text of the :title:`AGPL` license agreement, available in the distribution material (file COPYING) and `here <https://www.gnu.org/licenses/agpl-3.0.html>`_, to ensure that your use case complies with the guidelines of the license. If you determine you cannot meet the requirements of the :title:`AGPL`, please contact `Artifex <https://artifex.com/contact/pymupdf-inquiry.php?utm_source=rtd-pymupdf&utm_medium=rtd&utm_content=inline-link>`_ for more information regarding a commercial license.
+|PyMuPDF| and |MuPDF| are now available under both, open-source |AGPL| and commercial license agreements. Please read the full text of the |AGPL| license agreement, available in the distribution material (file COPYING) and `on the GNU license page <https://www.gnu.org/licenses/agpl-3.0.html>`_, to ensure that your use case complies with the guidelines of the license. If you determine you cannot meet the requirements of the |AGPL|, please contact `Artifex <https://artifex.com/contact/pymupdf-inquiry.php?utm_source=rtd-pymupdf&utm_medium=rtd&utm_content=inline-link>`_ for more information regarding a commercial license.
 
 .. raw:: html
 

docs/algebra.rst

@@ -74,7 +74,7 @@ a|b       **union rectangle:** "a" must be a rectangle, and "b" may be
 b in a    if "b" is a number, then `b in tuple(a)` is returned.
           If "b" is :data:`point_like`, :data:`rect_like` or :data:`quad_like`,
           then "a" must be a rectangle, and `a.contains(b)` is returned.
-a == b    *True* if *bool(a-b)* is *False* ("b" may be "a-like").
+a == b    ``True`` if *bool(a-b)* is ``False`` ("b" may be "a-like").
 ========= ===========================================================================
 
 

docs/annot.rst

@@ -8,7 +8,9 @@ Annot
 
 |pdf_only_class|
 
-Quote from the :ref:`AdobeManual`: "An annotation associates an object such as a note, sound, or movie with a location on a page of a PDF document, or provides a way to interact with the user by means of the mouse and keyboard."
+Quote from the :ref:`AdobeManual`:
+
+   *"An annotation associates an object such as a note, sound, or movie with a location on a page of a PDF document, or provides a way to interact with the user by means of the mouse and keyboard."*
 
 There is a parent-child relationship between an annotation and its page. If the page object becomes unusable (closed document, any document structure change, etc.), then so does every of its existing annotation objects -- an exception is raised saying that the object is "orphaned", whenever an annotation property or method is accessed.
 
@@ -78,18 +80,18 @@ There is a parent-child relationship between an annotation and its page. If the
 
       :arg int dpi: (new in v1.19.2) desired resolution in dots per inch. If not `None`, the matrix parameter is ignored.
 
-      :arg colorspace: a colorspace to be used for image creation. Default is *pymupdf.csRGB*.
+      :arg colorspace: a colorspace to be used for image creation. Default is ``pymupdf.csRGB``.
       :type colorspace: :ref:`Colorspace`
 
-      :arg bool alpha: whether to include transparency information. Default is *False*.
+      :arg bool alpha: whether to include transparency information. Default is ``False``.
 
       :rtype: :ref:`Pixmap`
 
       .. note::
 
          * If the annotation has just been created or modified, you should :meth:`Document.reload_page` the page first via `page = doc.reload_page(page)`.
 
-         * The pixmap will have *"premultiplied"* pixels if `alpha=True`. To learn about some background, e.g. look for "Premultiplied alpha" `here <https://en.wikipedia.org/wiki/Glossary_of_computer_graphics#P>`_.
+         * The pixmap will have *"premultiplied"* pixels if `alpha=True`. To learn about some background, e.g. look for "Premultiplied alpha" `in this online glossary <https://en.wikipedia.org/wiki/Glossary_of_computer_graphics#P>`_.
 
 
    .. index::
@@ -155,7 +157,7 @@ There is a parent-child relationship between an annotation and its page. If the
 
       * Changed in version 1.16.10
 
-      Changes annotation properties. These include dates, contents, subject and author (title). Changes for *name* and *id* will be ignored. The update happens selectively: To leave a property unchanged, set it to *None*. To delete existing data, use an empty string.
+      Changes annotation properties. These include dates, contents, subject and author (title). Changes for *name* and *id* will be ignored. The update happens selectively: To leave a property unchanged, set it to ``None``. To delete existing data, use an empty string.
 
       :arg dict info: a dictionary compatible with the *info* property (see below). All entries must be strings. If this argument is not a dictionary, the other arguments are used instead -- else they are ignored.
       :arg str content: *(new in v1.16.10)* see description in :attr:`info`.
@@ -237,7 +239,7 @@ There is a parent-child relationship between an annotation and its page. If the
       The annotation's blend mode. See :ref:`AdobeManual`, page 324 for explanations.
 
       :rtype: str
-      :returns: the blend mode or *None*.
+      :returns: the blend mode or ``None``.
 
 
    .. method:: set_blendmode(blendmode)
@@ -357,13 +359,13 @@ There is a parent-child relationship between an annotation and its page. If the
 
       :arg sequence,float fill_color: the fill color.
 
-      :arg bool cross_out: *(new in v1.17.2)* add two diagonal lines to the annotation rectangle. 'Redact' annotations only. If not desired, *False* must be specified even if the annotation was created with *False*.
+      :arg bool cross_out: *(new in v1.17.2)* add two diagonal lines to the annotation rectangle. 'Redact' annotations only. If not desired, ``False`` must be specified even if the annotation was created with ``False``.
 
       :arg int rotate: new rotation value. Default (-1) means no change. Supports 'FreeText' and several other annotation types (see :meth:`Annot.set_rotation`), [#f1]_. Only choose 0, 90, 180, or 270 degrees for 'FreeText'. Otherwise any integer is acceptable.
 
       :rtype: bool
 
-      This method is the only way to change the colors of a FreeText annotation. You cannot use `:meth:Annot.set_colors` for this purpose. But be aware that for rich-text annotations, the text color is never changed. The text color is set by the *text_color* entry of the *info* dictionary. This is a limitation of MuPDF and not a bug.
+      This method is the only way to change the colors of a FreeText annotation. You cannot use :meth:`Annot.set_colors` for this purpose. But be aware that for rich-text annotations, the text color is never changed. The text color is set by the ``text_color`` entry of the ``info`` dictionary. This is a limitation of |MuPDF| and not a bug.
 
       .. caution:: Using this method inside a :meth:`Page.annots` loop is **not recommended!** This is because most annotation updates require the owning page to be reloaded -- which cannot be done inside this loop. Please use the example coding pattern given in the documentation of this generator.
 
@@ -373,7 +375,7 @@ There is a parent-child relationship between an annotation and its page. If the
       Basic information of the annot's attached file.
 
       :rtype: dict
-      :returns: a dictionary with keys *filename*, *ufilename*, *desc* (description), *size* (uncompressed file size), *length* (compressed length) for FileAttachment annot types, else *None*.
+      :returns: a dictionary with keys *filename*, *ufilename*, *desc* (description), *size* (uncompressed file size), *length* (compressed length) for FileAttachment annot types, else ``None``.
 
    .. method:: get_file()
 
@@ -484,7 +486,7 @@ There is a parent-child relationship between an annotation and its page. If the
 
    .. attribute:: line_ends
 
-      A pair of integers specifying start and end symbol of annotations types 'FreeText', 'Line', 'PolyLine', and 'Polygon'. *None* if not applicable. For possible values and descriptions in this list, see the :ref:`AdobeManual`, table 1.76 on page 400.
+      A pair of integers specifying start and end symbol of annotations types 'FreeText', 'Line', 'PolyLine', and 'Polygon'. ``None`` if not applicable. For possible values and descriptions in this list, see the :ref:`AdobeManual`, table 1.76 on page 400.
 
       :rtype: tuple
 

docs/app1.rst

@@ -94,7 +94,7 @@ Example output::
 HTML
 ~~~~
 
-:meth:`TextPage.extractHTML` (or *Page.get_text("html")* output fully reflects the structure of the page's *TextPage* -- much like DICT / JSON below. This includes images, font information and text positions. If wrapped in HTML header and trailer code, it can readily be displayed by an internet browser. Our above example::
+:meth:`TextPage.extractHTML` (or *Page.get_text("html")* output fully reflects the structure of the page's ``TextPage`` -- much like DICT / JSON below. This includes images, font information and text positions. If wrapped in HTML header and trailer code, it can readily be displayed by an internet browser. Our above example::
 
     >>> for line in page.get_text("html").splitlines():
             print(line)
@@ -159,7 +159,7 @@ To address the font issue, you can use a simple utility script to scan through t
 DICT (or JSON)
 ~~~~~~~~~~~~~~~~
 
-:meth:`TextPage.extractDICT` (or *Page.get_text("dict", sort=False)*) output fully reflects the structure of a *TextPage* and provides image content and position detail (*bbox* -- boundary boxes in pixel units) for every block, line and span. Images are stored as *bytes* for DICT output and base64 encoded strings for JSON output.
+:meth:`TextPage.extractDICT` (or *Page.get_text("dict", sort=False)*) output fully reflects the structure of a ``TextPage`` and provides image content and position detail (*bbox* -- boundary boxes in pixel units) for every block, line and span. Images are stored as *bytes* for DICT output and base64 encoded strings for JSON output.
 
 For a visualization of the dictionary structure have a look at :ref:`textpagedict`.
 
@@ -266,7 +266,7 @@ XHTML
 
 Text Extraction Flags Defaults
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-* New in version 1.16.2: Method :meth:`Page.get_text` supports a keyword parameter *flags* *(int)* to control the amount and the quality of extracted data. The following table shows the defaults settings (flags parameter omitted or None) for each extraction variant. If you specify flags with a value other than *None*, be aware that you must set **all desired** options. A description of the respective bit settings can be found in :ref:`TextPreserve`.
+* New in version 1.16.2: Method :meth:`Page.get_text` supports a keyword parameter *flags* *(int)* to control the amount and the quality of extracted data. The following table shows the defaults settings (flags parameter omitted or None) for each extraction variant. If you specify flags with a value other than ``None``, be aware that you must set **all desired** options. A description of the respective bit settings can be found in :ref:`TextPreserve`.
 
 * New in v1.19.6: The default combinations in the following table are now available as Python constants: :data:`TEXTFLAGS_TEXT`, :data:`TEXTFLAGS_WORDS`, :data:`TEXTFLAGS_BLOCKS`, :data:`TEXTFLAGS_DICT`, :data:`TEXTFLAGS_RAWDICT`, :data:`TEXTFLAGS_HTML`, :data:`TEXTFLAGS_XHTML`, :data:`TEXTFLAGS_XML`, and :data:`TEXTFLAGS_SEARCH`. You can now easily modify a default flag, e.g.