Figure.text: Deprecate parameter "incols" to "use_word" (remove in v0…

….10.0) (GenericMappingTools#1964)

* Rename 'incols' to 'use_word'
* Replace -i placeholder with -it docstring
* Add 'deprecate_parameter' for two minor releases
* Remove 'i' or 'it' from 'kwargs_to_strings'
* Adjust docstring corresponding to 'use_word=<integer>'

Co-authored-by: Dongdong Tian <[email protected]>

pygmt/src/text.py

@@ -7,6 +7,7 @@
 from pygmt.helpers import (
     build_arg_string,
     data_kind,
+    deprecate_parameter,
     fmt_docstring,
     is_nonstr_iter,
     kwargs_to_strings,
@@ -15,6 +16,7 @@
 
 
 @fmt_docstring
+@deprecate_parameter("incols", "use_word", "v0.8.0", remove_version="v0.10.0")
 @use_alias(
     R="region",
     J="projection",
@@ -33,7 +35,7 @@
     e="find",
     f="coltypes",
     h="header",
-    i="incols",
+    it="use_word",
     p="perspective",
     t="transparency",
     w="wrap",
@@ -45,7 +47,6 @@
     font="sequence_comma",
     justify="sequence_comma",
     c="sequence_comma",
-    i="sequence_comma",
     p="sequence",
 )
 def text_(
@@ -156,7 +157,10 @@ def text_(
     {find}
     {coltypes}
     {header}
-    {incols}
+    use_word : int
+        Select a specific word from the trailing text, with the first
+        word being 0 [Default is the entire trailing text]. No numerical
+        columns can be specified.
     {perspective}
     {transparency}
         ``transparency`` can also be a 1d array to set varying