text() docstring update (#813)

* docstring update text()

    * Remove following line from docstring (appears to be copy/paste error from extrude())

       extrude always *adds* material to a part.

    * Swap order of :param distance: and :param fontsize: to match argument order

    * Mention fontsize is in model units (fix #463)

    * distance: mention distance is for both extrude/cut

    * Update kind default in docstring as "regular" not "Normal"

    * Add missing fontPath arg description

    * Add examples of usage

      - Using an installed system font

      - Using a font at provided path (when font not installed on system)

        I tested with the free fonts from http://www.gust.org.pl/projects/e-foundry/tex-gyre

      - Cut text into solid

    * Change docstring to fix autodoc-typehints issue where the Parameters section is duplicated (see screenshot)

* Update cadquery/cq.py

Co-authored-by: Marcus Boyd <[email protected]>

* Update cadquery/cq.py

Co-authored-by: Marcus Boyd <[email protected]>

* Update cadquery/cq.py

Co-authored-by: Marcus Boyd <[email protected]>

* Update cadquery/cq.py

Co-authored-by: Marcus Boyd <[email protected]>

* Update cadquery/cq.py

Co-authored-by: Marcus Boyd <[email protected]>

* Update cadquery/cq.py

Co-authored-by: Marcus Boyd <[email protected]>

* Update cadquery/cq.py

Co-authored-by: Marcus Boyd <[email protected]>

* Update cadquery/cq.py

Co-authored-by: Marcus Boyd <[email protected]>

* Update cadquery/cq.py

Co-authored-by: Marcus Boyd <[email protected]>

* Update cadquery/cq.py

Co-authored-by: Marcus Boyd <[email protected]>

Co-authored-by: Marcus Boyd <[email protected]>

Author: lorenzncode

cadquery/cq.py

@@ -3919,28 +3919,43 @@ def text(
         """
         Create a 3D text
 
-        :param str txt: text to be rendered
-        :param distance: the distance to extrude, normal to the workplane plane
+        :param txt: text to be rendered
+        :param fontsize: size of the font in model units
+        :param distance: the distance to extrude or cut, normal to the workplane plane
         :type distance: float, negative means opposite the normal direction
-        :param float fontsize: size of the font
-        :param boolean cut: True to cut the resulting solid from the parent solids if found.
-        :param boolean combine: True to combine the resulting solid with parent solids if found.
-        :param boolean clean: call :py:meth:`clean` afterwards to have a clean shape
-        :param str font: fontname (default: Arial)
-        :param str kind: font type (default: Normal)
-        :param str halign: horizontal alignment (default: center)
-        :param str valign: vertical alignment (default: center)
-        :return: a CQ object with the resulting solid selected.
-
-        extrude always *adds* material to a part.
-
-        The returned object is always a CQ object, and depends on whether combine is True, and
+        :param cut: True to cut the resulting solid from the parent solids if found
+        :param combine: True to combine the resulting solid with parent solids if found
+        :param clean: call :py:meth:`clean` afterwards to have a clean shape
+        :param font: font name
+        :param fontPath: path to font file
+        :param kind: font type
+        :param halign: horizontal alignment
+        :param valign: vertical alignment
+        :return: a CQ object with the resulting solid selected
+
+        The returned object is always a Workplane object, and depends on whether combine is True, and
         whether a context solid is already defined:
 
         *  if combine is False, the new value is pushed onto the stack.
         *  if combine is true, the value is combined with the context solid if it exists,
            and the resulting solid becomes the new context solid.
 
+        Examples::
+
+            cq.Workplane().text("CadQuery", 5, 1)
+
+        Specify the font (name), and kind to use an installed system font::
+
+            cq.Workplane().text("CadQuery", 5, 1, font="Liberation Sans Narrow", kind="italic")
+
+        Specify fontPath to use a font from a given file::
+
+            cq.Workplane().text("CadQuery", 5, 1, fontPath="/opt/fonts/texgyrecursor-bold.otf")
+
+        Cutting text into a solid::
+
+            cq.Workplane().box(8, 8, 8).faces(">Z").workplane().text("Z", 5, -1.0)
+
         """
         r = Compound.makeText(
             txt,