minor documentation updates

JorjMcKie · JorjMcKie · commit 3460e77386e2 · 2020-06-25T11:39:49.000-04:00
diff --git a/docs/annot.rst b/docs/annot.rst
@@ -146,14 +146,14 @@ There is a parent-child relationship between an annotation and its page. If the
 
    .. method:: setRotation(angle)
 
-      Set the rotation of an annotation. This rotates the annotation rectangle around its center point. Then a **new rectangle** is calculated which replaces the existing one.
+      Set the rotation of an annotation. This rotates the annotation rectangle around its center point. Then a **new annotation rectangle** is calculated from the resulting quad.
 
-      :arg int angle: rotation angle in degrees. Arbitrary values are possible, but will be replaced by equivalent values 0 <= angle < 360.
+      :arg int angle: rotation angle in degrees. Arbitrary values are possible, but will be clamped to the interval 0 <= angle < 360.
 
       .. note::
         * You **must invoke** :meth:`Annot.update` to activate the effect.
-        * For PDF_ANNOT_FREE_TEXT, only the four values 0, 90, 180 and 270 are possible and will only **rotate the text** inside the current rectangle (which remains unchanged). Other values are silently ignored and treated as 0.
-        * Otherwise, only the following `AnnotationTypes`_ can be rotated: 'Square', 'Circle', 'Caret', 'Text', 'FileAttachment', 'Ink', 'Line', 'Polyline', 'Polygon', and 'Stamp'. For all others the method is a no-op.
+        * For PDF_ANNOT_FREE_TEXT, only one of the values 0, 90, 180 and 270 is possible and will **rotate the text** inside the current rectangle (which remains unchanged). Other values are silently ignored and replaced by 0.
+        * Otherwise, only the following :ref:`AnnotationTypes` can be rotated: 'Square', 'Circle', 'Caret', 'Text', 'FileAttachment', 'Ink', 'Line', 'Polyline', 'Polygon', and 'Stamp'. For all others the method is a no-op.
 
 
    .. method:: setBorder(border=None, width=0, style=None, dashes=None)
@@ -225,7 +225,7 @@ There is a parent-child relationship between an annotation and its page. If the
           * 'Line', 'Polyline', 'Polygon' annotations: use it to give applicable line end symbols a fill color other than that of the annotation *(changed in v1.16.16)*.
 
       :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 `Annot.setRotation`), [#f1]_. Only choose 0, 90, 180, or 270 degrees for 'FreeText'. Otherwise any integer is acceptable.
+      :arg int rotate: new rotation value. Default (-1) means no change. Supports 'FreeText' and several other annotation types (see :meth:`Annot.setRotation`), [#f1]_. Only choose 0, 90, 180, or 270 degrees for 'FreeText'. Otherwise any integer is acceptable.
 
       :rtype: bool
 
diff --git a/docs/classes.rst b/docs/classes.rst
@@ -5,24 +5,24 @@ Classes
 .. toctree::
    :maxdepth: 2
 
-   annot.rst
-   colorspace.rst
-   displaylist.rst
-   document.rst
-   font.rst
-   identity.rst
-   irect.rst
-   link.rst
-   linkdest.rst
-   matrix.rst
-   outline.rst
-   page.rst
-   pixmap.rst
-   point.rst
-   quad.rst
-   rect.rst
-   shape.rst
-   textpage.rst
-   textwriter.rst
-   tools.rst
-   widget.rst
+   annot
+   colorspace
+   displaylist
+   document
+   font
+   identity
+   irect
+   link
+   linkdest
+   matrix
+   outline
+   page
+   pixmap
+   point
+   quad
+   rect
+   shape
+   textpage
+   textwriter
+   tools
+   widget
diff --git a/docs/conf.py b/docs/conf.py
@@ -29,7 +29,7 @@
 templates_path = ["_templates"]
 
 # The suffix of source filenames.
-source_suffix = ".rst"
+# source_suffix = ".rst"
 
 # The encoding of source files.
 # source_encoding = 'utf-8-sig'
@@ -95,9 +95,9 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 # html_theme = "agogo"
-html_theme = "sphinxdoc"
+# html_theme = "sphinxdoc"
 # html_theme = "python_docs_theme"
-# html_theme = "sphinx_rtd_theme"
+html_theme = "sphinx_rtd_theme"
 # html_theme = "classic"
 
 # Theme options are theme-specific and customize the look and feel of a theme
@@ -165,8 +165,8 @@
 html_split_index = True
 
 # If true, links to the reST sources are added to the pages.
-html_show_sourcelink = False
-
+html_show_sourcelink = True
+html_sourcelink_suffix = ".rst"
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
 html_show_sphinx = True
 
@@ -176,10 +176,10 @@
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the
 # base URL from which the finished HTML is served.
-# html_use_opensearch = ""
+html_use_opensearch = "https://pymupdf.readthedocs.io/en/latest"
 
 # This is the file name suffix for HTML files (e.g. ".xhtml").
-html_file_suffix = ".html"
+# html_file_suffix = ".html"
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = "PyMuPDF"
diff --git a/docs/index.rst b/docs/index.rst
@@ -4,19 +4,19 @@
 .. toctree::
    :maxdepth: 4
 
-   intro.rst
-   installation.rst
-   tutorial.rst
-   faq.rst
-   module.rst
-   classes.rst
-   algebra.rst
-   lowlevel.rst
-   glossary.rst
-   vars.rst
-   colors.rst
-   app1.rst
-   app2.rst
-   app3.rst
-   app4.rst
-   changes.rst
+   intro
+   installation
+   tutorial
+   faq
+   module
+   classes
+   algebra
+   lowlevel
+   glossary
+   vars
+   colors
+   app1
+   app2
+   app3
+   app4
+   changes
diff --git a/docs/lowlevel.rst b/docs/lowlevel.rst
@@ -6,6 +6,6 @@ Contains a number of functions and classes for the experienced user. To be used
 .. toctree::
    :maxdepth: 1
 
-   functions.rst
-   device.rst
-   coop_low.rst
+   functions
+   device
+   coop_low
diff --git a/docs/page.rst b/docs/page.rst
@@ -21,9 +21,10 @@ In a nutshell, this is what you can do with PyMuPDF:
 * Add annotations and form fields.
 
 .. note::
-   Many methods require coordinates (mostly points or rectangles) to put new content in the right place. Please be aware that these coordinates **must always** be provided relative to the **unrotated** page. And vice versa: all methods / attributes returning coordinates of page objects will present them as if the page were not rotated. This applies to text extraction, annotation rectangles, image bboxes, etc.
 
-   So the returned value of e.g. :meth:`Page.getImageBbox` will not change if you do a :meth:`Page.setRotation`. The same is true for coordinates returned by :meth:`Page.getText`, annotation rectangles, and so on. If you want to find out, where an object is located in **rotated coordinates**, multiplay the coordinates by :attr:`Page.rotationMatrix`. There also is its inverse, :attr:`Page.derotationMatrix`, which you can use when interfacing with other readers, which may behave differently in this respect.
+   Methods require coordinates (points, rectangles) to put content in desired places. Please be aware that since v1.17.0 these coordinates **must always** be provided relative to the **unrotated** page. The reverse is also true: all coordinates returned by methods and attributes pertain to the unrotated page.
+
+   So the returned value of e.g. :meth:`Page.getImageBbox` will not change if you do a :meth:`Page.setRotation`. The same is true for coordinates returned by :meth:`Page.getText`, annotation rectangles, and so on. If you want to find out, where an object is located in **rotated coordinates**, multiply the coordinates with :attr:`Page.rotationMatrix`. There also is its inverse, :attr:`Page.derotationMatrix`, which you can use when interfacing with other readers, which may behave differently in this respect.
 
 ================================= =======================================================
 **Method / Attribute**            **Short Description**
diff --git a/docs/shape.rst b/docs/shape.rst
@@ -302,7 +302,7 @@ Several draw methods can be executed in a row and each one of them will contribu
 
       Finish a set of *draw*()* methods by applying :ref:`CommonParms` to all of them. This method also supports morphing the resulting compound drawing using a fixpoint :ref:`Point`.
 
-      :arg sequence morph: morph the text or the compound drawing around some arbitrary :ref:`Point` *fixpoint* by applying :ref:`Matrix` *matrix* to it. This implies that *fixpoint* is a **fixed point** of this operation. Default is no morphing (*None*). The matrix can contain any values in its first 4 components, *matrix.e == matrix.f == 0* must be true, however. This means that any combination of scaling, shearing, rotating, flipping, etc. is possible, but translations are not.
+      :arg sequence morph: morph the text or the compound drawing around some arbitrary :ref:`Point` *fixpoint* by applying :ref:`Matrix` *matrix* to it. This implies that *fixpoint* is a **fixed point** of this operation: it will not change its position. Default is no morphing (*None*). The matrix can contain any values in its first 4 components, *matrix.e == matrix.f == 0* must be true, however. This means that any combination of scaling, shearing, rotating, flipping, etc. is possible, but translations are not.
 
       :arg bool even_odd: request the **"even-odd rule"** for filling operations. Default is *False*, so that the **"nonzero winding number rule"** is used. These rules are alternative methods to apply the fill color where areas overlap. Only with fairly complex shapes a different behavior is to be expected with these rules. For an in-depth explanation, see :ref:`AdobeManual`, pp. 232 ff. Here is an example to demonstrate the difference.
 
diff --git a/docs/textwriter.rst b/docs/textwriter.rst
@@ -67,7 +67,7 @@ There also exists :meth:`Page.writeText` which is able to combine one or more Te
       :arg page: write to this :ref:`Page`.
       :arg float opacity: override the value of the TextWriter for this output.
       :arg sequ color: override the value of the TextWriter for this output.
-      :arg sequ morph: modify the text appearance by applying a matrix to it. If provided, this must be a sequence *(fixpoint, matrix)* with a point-like *fixpoint* and a matrix-like *matrix*. A typical example is rotating the text around *fixpoint*.
+      :arg sequ morph: modify the text appearance by applying a matrix to it. If provided, this must be a sequence *(fixpoint, matrix)* with a point-like *fixpoint* and a matrix-like *matrix*. A typical example is rotating the text around *fixpoint*. 
       :arg bool overlay: put in foreground (default) or background.
 
 
diff --git a/docs/vars.rst b/docs/vars.rst
@@ -256,56 +256,67 @@ Link Destination Flags
 
     :rtype: bool
 
-.. _AnnotationTypes:
 
 Annotation Related Constants
 -----------------------------
-See chapter 8.4.5, pp. 615 of the :ref:`AdobeManual` for more details.
+See chapter 8.4.5, pp. 615 of the :ref:`AdobeManual` for details.
+
+.. _AnnotationTypes:
 
-**Annotation Types**::
+Annotation Types
+~~~~~~~~~~~~~~~~~
+::
 
     PDF_ANNOT_TEXT 0
     PDF_ANNOT_LINK 1
-    PDF_ANNOT_FREETEXT 2
+    PDF_ANNOT_FREE_TEXT 2
     PDF_ANNOT_LINE 3
     PDF_ANNOT_SQUARE 4
     PDF_ANNOT_CIRCLE 5
     PDF_ANNOT_POLYGON 6
-    PDF_ANNOT_POLYLINE 7
+    PDF_ANNOT_POLY_LINE 7
     PDF_ANNOT_HIGHLIGHT 8
     PDF_ANNOT_UNDERLINE 9
     PDF_ANNOT_SQUIGGLY 10
-    PDF_ANNOT_STRIKEOUT 11
+    PDF_ANNOT_STRIKE_OUT 11
     PDF_ANNOT_REDACT 12
     PDF_ANNOT_STAMP 13
     PDF_ANNOT_CARET 14
     PDF_ANNOT_INK 15
     PDF_ANNOT_POPUP 16
-    PDF_ANNOT_FILEATTACHMENT 17
+    PDF_ANNOT_FILE_ATTACHMENT 17
     PDF_ANNOT_SOUND 18
     PDF_ANNOT_MOVIE 19
     PDF_ANNOT_WIDGET 20
     PDF_ANNOT_SCREEN 21
-    PDF_ANNOT_PRINTERMARK 22
-    PDF_ANNOT_TRAPNET 23
+    PDF_ANNOT_PRINTER_MARK 22
+    PDF_ANNOT_TRAP_NET 23
     PDF_ANNOT_WATERMARK 24
     PDF_ANNOT_3D 25
+    PDF_ANNOT_UNKNOWN -1
 
+.. _AnnotationFlags:
 
-**Annotation Flag Bits**::
+Annotation Flag Bits
+~~~~~~~~~~~~~~~~~~~~~
+::
 
-    PDF_ANNOT_IS_Invisible 1 << (1-1)
-    PDF_ANNOT_IS_Hidden 1 << (2-1)
-    PDF_ANNOT_IS_Print 1 << (3-1)
-    PDF_ANNOT_IS_NoZoom 1 << (4-1)
-    PDF_ANNOT_IS_NoRotate 1 << (5-1)
-    PDF_ANNOT_IS_NoView 1 << (6-1)
-    PDF_ANNOT_IS_ReadOnly 1 << (7-1)
-    PDF_ANNOT_IS_Locked 1 << (8-1)
-    PDF_ANNOT_IS_ToggleNoView 1 << (9-1)
-    PDF_ANNOT_IS_LockedContents 1 << (10-1)
+    PDF_ANNOT_IS_INVISIBLE 1 << (1-1)
+    PDF_ANNOT_IS_HIDDEN 1 << (2-1)
+    PDF_ANNOT_IS_PRINT 1 << (3-1)
+    PDF_ANNOT_IS_NO_ZOOM 1 << (4-1)
+    PDF_ANNOT_IS_NO_ROTATE 1 << (5-1)
+    PDF_ANNOT_IS_NO_VIEW 1 << (6-1)
+    PDF_ANNOT_IS_READ_ONLY 1 << (7-1)
+    PDF_ANNOT_IS_LOCKED 1 << (8-1)
+    PDF_ANNOT_IS_TOGGLE_NO_VIEW 1 << (9-1)
+    PDF_ANNOT_IS_LOCKED_CONTENTS 1 << (10-1)
 
-**Annotation Line Ending Styles**::
+.. _AnnotationLineEnds:
+
+Annotation Line Ending Styles
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+::
 
     PDF_ANNOT_LE_NONE 0
     PDF_ANNOT_LE_SQUARE 1
@@ -322,7 +333,11 @@ See chapter 8.4.5, pp. 615 of the :ref:`AdobeManual` for more details.
 Widget Constants
 -----------------
 
-**Widget types** (*field_type*)::
+.. _WidgetTypes:
+
+Widget Types (*field_type*)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+::
 
     PDF_WIDGET_TYPE_UNKNOWN 0
     PDF_WIDGET_TYPE_BUTTON 1
@@ -333,7 +348,9 @@ Widget Constants
     PDF_WIDGET_TYPE_SIGNATURE 6
     PDF_WIDGET_TYPE_TEXT 7
 
-**Text Widget Subtypes** (*text_format*)::
+Text Widget Subtypes (*text_format*)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+::
 
     PDF_WIDGET_TX_FORMAT_NONE 0
     PDF_WIDGET_TX_FORMAT_NUMBER 1
