Documentation: Round 2 of syntax updates.

Author: jamie-lemon

docs/README.md

@@ -14,8 +14,8 @@ Within `docs` update the associated restructured text (`.rst`) files. These file
 
 ### Conventions
 
-- Code parameters should be referenced within backticks, not italics, double backtick is better for safety
-- When referencing names of common things surround with | , e.g. |PyMuPDF| , not PyMuPDF, see `header.rst` for names listing
+- 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>`"

docs/font.rst

@@ -8,9 +8,9 @@ Font
 
 * New in v1.16.18
 
-This class represents a font as defined in MuPDF (*fz_font_s* structure). It is required for the new class :ref:`TextWriter` and the new :meth:`Page.write_text`. Currently, it has no connection to how fonts are used in methods :meth:`Page.insert_text` or :meth:`Page.insert_textbox`, respectively.
+This class represents a font as defined in |MuPDF| (``fz_font_s`` structure). It is required for the new class :ref:`TextWriter` and the new :meth:`Page.write_text`. Currently, it has no connection to how fonts are used in methods :meth:`Page.insert_text` or :meth:`Page.insert_textbox`, respectively.
 
-A Font object also contains useful general information, like the font bbox, the number of defined glyphs, glyph names or the bbox of a single glyph.
+A ``Font`` object also contains useful general information, like the font bbox, the number of defined glyphs, glyph names or the ``bbox`` of a single glyph.
 
 
 ==================================== ============================================
@@ -74,7 +74,7 @@ A Font object also contains useful general information, like the font bbox, the
       :arg bool is_italic: look for an italic font.
       :arg bool is_serif: look for a serifed font.
 
-      :returns: a MuPDF font if successful. This is the overall sequence of checks to determine an appropriate font:
+      :returns: a |MuPDF| font if successful. This is the overall sequence of checks to determine an appropriate font:
 
          =========== ============================================================
          Argument    Action
@@ -138,9 +138,9 @@ A Font object also contains useful general information, like the font bbox, the
 
    .. method:: has_glyph(chr, language=None, script=0, fallback=False)
 
-      Check whether the unicode *chr* exists in the font or (option) some fallback font. May be used to check whether any "TOFU" symbols will appear on output.
+      Check whether the unicode ``chr`` exists in the font or (option) some fallback font. May be used to check whether any "TOFU" symbols will appear on output.
 
-      :arg int chr: the unicode of the character (i.e. *ord()*).
+      :arg int chr: the unicode of the character (i.e. ``ord()``).
       :arg str language: the language -- currently unused.
       :arg int script: the UCDN script number.
       :arg bool fallback: *(new in v1.17.5)* perform an extended search in fallback fonts or restrict to current font (default).
@@ -152,7 +152,7 @@ A Font object also contains useful general information, like the font bbox, the
 
       Return an array of unicodes supported by this font.
 
-      :returns: an *array.array* [#f2]_ of length at most :attr:`Font.glyph_count`. I.e. *chr()* of every item in this array has a glyph in the font without using fallbacks. This is an example display of the supported glyphs:
+      :returns: an ``array.array`` [#f2]_ of length at most :attr:`Font.glyph_count`. I.e. ``chr()`` of every item in this array has a glyph in the font without using fallbacks. This is an example display of the supported glyphs:
 
          >>> import pymupdf
          >>> font = pymupdf.Font("math")
@@ -191,8 +191,8 @@ A Font object also contains useful general information, like the font bbox, the
 
       Calculate the "width" of the character's glyph (visual representation).
 
-      :arg int chr: the unicode number of the character. Use *ord()*, not the character itself. Again, this should normally work even if a character is not supported by that font, because fallback fonts will be checked where necessary.
-      :arg int wmode: write mode, 0 = horizontal, 1 = vertical.
+      :arg int chr: the unicode number of the character. Use ``ord()``, not the character itself. Again, this should normally work even if a character is not supported by that font, because fallback fonts will be checked where necessary.
+      :arg int wmode: write mode, ``0`` = horizontal, ``1`` = vertical.
 
       The other parameters are not in use currently.
 
@@ -218,7 +218,7 @@ A Font object also contains useful general information, like the font bbox, the
 
       The glyph rectangle relative to :data:`fontsize` 1.
 
-      :arg int chr: *ord()* of the character.
+      :arg int chr: ``ord()`` of the character.
 
       :returns: a :ref:`Rect`.
 
@@ -227,7 +227,7 @@ A Font object also contains useful general information, like the font bbox, the
 
       Show the name of the character's glyph.
 
-      :arg int ch: the unicode number of the character. Use *ord()*, not the character itself.
+      :arg int ch: the unicode number of the character. Use ``ord()``, not the character itself.
 
       :returns: a string representing the glyph's name. E.g. `font.glyph_name(ord("#")) = "numbersign"`. For an invalid code ".notfound" is returned.
 
@@ -340,15 +340,15 @@ A Font object also contains useful general information, like the font bbox, the
 
       * New in v1.18.0
 
-      The ascender value of the font, see `here <https://en.wikipedia.org/wiki/Ascender_(typography)>`_ for details. Please note that there is a difference to the strict definition: our value includes everything above the baseline -- not just the height difference between upper case "A" and and lower case "a".
+      The ascender value of the font, see `ascender typography <https://en.wikipedia.org/wiki/Ascender_(typography)>`_ for details. Please note that there is a difference to the strict definition: our value includes everything above the baseline -- not just the height difference between upper case "A" and and lower case "a".
 
       :rtype: float
 
    .. attribute:: descender
 
       * New in v1.18.0
 
-      The descender value of the font, see `here <https://en.wikipedia.org/wiki/Descender>`_ for details. This value always is negative and is the portion that some glyphs descend below the base line, for example "g" or "y". As a consequence, the value `ascender - descender` is the total height, that every glyph of the font fits into. This is true at least for most fonts -- as always, there are exceptions, especially for calligraphic fonts, etc.
+      The descender value of the font, see `descender typography <https://en.wikipedia.org/wiki/Descender>`_ for details. This value always is negative and is the portion that some glyphs descend below the base line, for example "g" or "y". As a consequence, the value `ascender - descender` is the total height, that every glyph of the font fits into. This is true at least for most fonts -- as always, there are exceptions, especially for calligraphic fonts, etc.
 
       :rtype: float
 

docs/functions.rst

@@ -132,9 +132,9 @@ Yet others are handy, general-purpose utilities.
           Write to Python's `logging` system using specified level.
       :arg str pylogging_name:
           Write to Python's `logging` system using specified logger name.
-          Only used if `pylogging_logger` is None. Default is `pymupdf`.
+          Only used if `pylogging_logger` is ``None``. Default is `pymupdf`.
 
-      If any `pylogging*` arg is not None, we write to `Python's logging system
+      If any `pylogging*` arg is not ``None``, we write to `Python's logging system
       <https://docs.python.org/3/library/logging.html>`_.
 
 -----
@@ -172,7 +172,7 @@ Yet others are handy, general-purpose utilities.
       :arg str name: the name of some glyph. The function is based on the `Adobe Glyph List <https://github.com/adobe-type-tools/agl-aglfn/blob/master/glyphlist.txt>`_.
 
       :rtype: int
-      :returns: the unicode. Invalid *name* entries return `0xfffd (65533)`.
+      :returns: the unicode. Invalid ``name`` entries return `0xfffd (65533)`.
 
       .. note:: A similar functionality is provided by package `fontTools <https://pypi.org/project/fonttools/>`_ in its *agl* sub-package.
 
@@ -412,7 +412,7 @@ Yet others are handy, general-purpose utilities.
       Calculate the length of text on output with a given **builtin** font, :data:`fontsize` and encoding.
 
       :arg str text: the text string.
-      :arg str fontname: the fontname. Must be one of either the :ref:`Base-14-Fonts` or the CJK fonts, identified by their "reserved" fontnames (see table in :meth:`Page.insert_font`).
+      :arg str fontname: the font name. Must be one of either the :ref:`Base-14-Fonts` or the CJK fonts, identified by their "reserved" fontnames (see table in :meth:`Page.insert_font`).
       :arg float fontsize: the :data:`fontsize`.
       :arg int encoding: the encoding to use. Besides 0 = Latin, 1 = Greek and 2 = Cyrillic (Russian) are available. Relevant for Base-14 fonts "Helvetica", "Courier" and "Times" and their variants only. Make sure to use the same value as in the corresponding text insertion.
       :rtype: float

docs/how-to-open-a-file.rst

@@ -32,7 +32,7 @@ To open a file, do the following:
     doc = pymupdf.open("a.pdf")
 
 
-.. note:: The above creates a :ref:`Document`. The instruction `doc = pymupdf.Document("a.pdf")` does exactly the same. So, `open` is just a convenient alias  and you can find its full API documented in that chapter. 
+.. note:: The above creates a :ref:`Document`. The instruction `doc = pymupdf.Document("a.pdf")` does exactly the same. So, `open` is just a convenient alias and you can find its full API documented in that chapter.
 
 
 File Recognizer: Opening with :index:`a Wrong File Extension <pair: wrong; file extension>`

docs/installation.rst

@@ -30,7 +30,7 @@ For example:
 Installation
 ---------------------------------------------------------
 
-PyMuPDF should be installed using pip with::
+|PyMuPDF| should be installed using pip with::
 
   pip install --upgrade pymupdf
 

docs/irect.rst

@@ -75,7 +75,7 @@ IRect is a rectangular bounding box, very similar to :ref:`Rect`, except that al
       Checks whether *x* is contained in the rectangle. It may be :data:`rect_like`, :data:`point_like` or a number. If *x* is an empty rectangle, this is always true. Conversely, if the rectangle is empty this is always ``False``, if *x* is not an empty rectangle and not a number. If *x* is a number, it will be checked to be one of the four components. *x in irect* and *irect.contains(x)* are equivalent.
 
       :arg x: the object to check.
-      :type x: :ref:`IRect` or :ref:`Rect` or :ref:`Point` or int
+      :type x: :ref:`IRect` or :ref:`Rect` or :ref:`Point` or `int`.
 
       :rtype: bool
 

docs/matrix.rst

@@ -9,7 +9,7 @@ Matrix
 Matrix is a row-major 3x3 matrix used by image transformations in MuPDF (which complies with the respective concepts laid down in the :ref:`AdobeManual`). With matrices you can manipulate the rendered image of a page in a variety of ways: (parts of) the page can be rotated, zoomed, flipped, sheared and shifted by setting some or all of just six float values.
 
 
-Since all points or pixels live in a two-dimensional space, one column vector of that matrix is a constant unit vector, and only the remaining six elements are used for manipulations. These six elements are usually represented by *[a, b, c, d, e, f]*. Here is how they are positioned in the matrix:
+Since all points or pixels live in a two-dimensional space, one column vector of that matrix is a constant unit vector, and only the remaining six elements are used for manipulations. These six elements are usually represented by `[a, b, c, d, e, f]`. Here is how they are positioned in the matrix:
 
 .. image:: images/img-matrix.*
 

docs/module.rst

@@ -164,7 +164,7 @@ Example: To join the following files
 
 and store the result as **output.pdf** enter this command:
 
-*pymupdf join -o output.pdf file1.pdf,,N-1 file2.pdf,secret,N,1 file3.pdf,,5-N*
+``pymupdf join -o output.pdf file1.pdf,,N-1 file2.pdf,secret,N,1 file3.pdf,,5-N``
 
 
 Low Level Information

docs/outline.rst

@@ -6,7 +6,7 @@
 Outline
 ================
 
-*outline* (or "bookmark"), is a property of *Document*. If not ``None``, it stands for the first outline item of the document. Its properties in turn define the characteristics of this item and also point to other outline items in "horizontal" or downward direction. The full tree of all outline items for e.g. a conventional table of contents (TOC) can be recovered by following these "pointers".
+The document outline (otherwise known as "bookmarks") is a property of :ref:`Document` (see :attr:`Document.outline`). If not ``None``, it stands for the first outline item of the document. Its properties in turn define the characteristics of this item and also point to other outline items in "horizontal" or downward direction. The full tree of all outline items for e.g. a conventional table of contents (TOC) can be recovered by following these "pointers".
 
 ============================ ==================================================
 **Method / Attribute**       **Short Description**

docs/pixmap.rst

@@ -91,7 +91,7 @@ Have a look at the :ref:`FAQ` section to see some pixmap usage "at work".
       :type colorspace: :ref:`Colorspace`
 
       :arg source: the source pixmap.
-      :type source: ``Pixmap``
+      :type source: :ref:`Pixmap`.
 
    .. method:: __init__(self, source, mask)
 
@@ -100,17 +100,17 @@ Have a look at the :ref:`FAQ` section to see some pixmap usage "at work".
       **Copy and add image mask:** Copy *source* pixmap, add an alpha channel with transparency data from a mask pixmap.
 
       :arg source: pixmap without alpha channel.
-      :type source: :ref:`Pixmap`
+      :type source: :ref:`Pixmap`.
 
       :arg mask: a mask pixmap. Must be a graysale pixmap.
-      :type mask: :ref:`Pixmap`
+      :type mask: :ref:`Pixmap`.
 
    .. method:: __init__(self, source, width, height, [clip])
 
       **Copy and scale:** Copy *source* pixmap, scaling new width and height values -- the image will appear stretched or shrunk accordingly. Supports partial copying. The source colorspace may be ``None``.
 
       :arg source: the source pixmap.
-      :type source: ``Pixmap``
+      :type source: :ref:`Pixmap`.
 
       :arg float width: desired target width.
 
@@ -125,7 +125,7 @@ Have a look at the :ref:`FAQ` section to see some pixmap usage "at work".
       **Copy and add or drop alpha:** Copy *source* and add or drop its alpha channel. Identical copy if *alpha* equals *source.alpha*. If an alpha channel is added, its values will be set to 255.
 
       :arg source: source pixmap.
-      :type source: ``Pixmap``
+      :type source: :ref:`Pixmap`.
 
       :arg bool alpha: whether the target will have an alpha channel, default and mandatory if source colorspace is ``None``.
 
@@ -394,7 +394,7 @@ Have a look at the :ref:`FAQ` section to see some pixmap usage "at work".
       Create a Pillow Image from the pixmap. PIL / Pillow must be installed.
 
       :raises ImportError: if Pillow is not installed.
-      :returns: a ˇˇPIL.Imageˇˇ object
+      :returns: a ``PIL.Image`` object
 
    ..  method:: pil_save(*args, unmultiply=False, **kwargs)
 
@@ -406,7 +406,7 @@ Have a look at the :ref:`FAQ` section to see some pixmap usage "at work".
 
       A simple example: `pix.pil_save("some.webp", optimize=True, dpi=(150, 150))`.
 
-      :arg bool unmultiply: If the pixmap's colorspace is RGB with transparency, the alpha values may or may not already be multiplied into the color components ref/green/blue (called "premultiplied"). To enforce undoing premultiplication, set this parameter to `True`. To learn about some background, e.g. look for "Premultiplied alpha" `here <https://en.wikipedia.org/wiki/Glossary_of_computer_graphics#P>`_.
+      :arg bool unmultiply: If the pixmap's colorspace is RGB with transparency, the alpha values may or may not already be multiplied into the color components ref/green/blue (called "premultiplied"). To enforce undoing premultiplication, set this parameter to `True`. To learn about some background, e.g. look for `"Premultiplied alpha" on this page <https://en.wikipedia.org/wiki/Glossary_of_computer_graphics#P>`_.
 
 
       For details on other parameters see the Pillow documentation.