WIP: Toy implementation of automatic translation of GMT docs to PyGMT docstrings

[seisman]

Description of proposed changes

This branch provides a script to "automatically" convert GMT documentation to PyGMT docstrings.

Trying to address #895.

Feel free to play with the script and make changes directly to this branch (if you have the right permission). Comments are welcomed.

Reminders

• Run make format and make check to make sure the code follows the style guide.
• Add tests for new features or tests that would have caught the bug that you're fixing.
• Add new public functions/methods/classes to doc/api/index.rst.
• Write detailed docstrings for all functions/methods.
• If adding new functionality, add an example to docstrings or tutorials.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash commands are:

• /format: automatically format and lint the code
• /test-gmt-dev: run full tests on the latest GMT development version

[seisman]

Output of the script:

Details

Diff view:

--- 
+++ 
@@ -1,6 +1,6 @@
 
     Select painting or dumping country polygons from the Digital Chart of the World.
-    This is another dataset independent of GSHHG and hence the **-A** and **-D** options do not apply.
+    This is another dataset independent of GSHHG and hence the **area_thresh** and **resolution** options do not apply.
     Append one or more comma-separated countries using the
     `2-character ISO 3166-1 alpha-2 convention <https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2>`_.
     To select a state of a country
@@ -10,11 +10,11 @@
     NA (North America), or SA (South America).  Append **+l** to
     just list the countries and their codes [no data extraction or plotting takes place].
     Use **+L** to see states/territories for Argentina, Australia, Brazil, Canada, China, India, Russia and the US.
-    Finally, you can append **+l**\|\ **+L** to **-E**\ =\ *continent* to only list countries in that continent;
+    Finally, you can append **+l**\|\ **+L** to **dcw**\ =\ *continent* to only list countries in that continent;
     repeat if more than one continent is requested.
     Append **+p**\ *pen* to draw polygon outlines [no outline] and
     **+g**\ *fill* to fill them [no fill].  One of **+p**\|\ **g** must be
-    specified unless **-M** is in effect, in which case only one **-E** option can be given;
+    specified unless **-M** is in effect, in which case only one **dcw** option can be given;
     append **+z** to place the country code in the segment headers via **-Z**\ *code* settings.
-    Otherwise, you may repeat **-E** to give different groups of items their own pen/fill settings.
-    If neither **-J** nor **-M** are set then we just print the **-R**\ *wesn* string.
+    Otherwise, you may repeat **dcw** to give different groups of items their own pen/fill settings.
+    If neither **projection** nor **-M** are set then we just print the **region**\ *wesn* string.


Raw GMT docstring:


    Select painting or dumping country polygons from the Digital Chart of the World.
    This is another dataset independent of GSHHG and hence the **-A** and **-D** options do not apply.
    Append one or more comma-separated countries using the
    `2-character ISO 3166-1 alpha-2 convention <https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2>`_.
    To select a state of a country
    (if available), append .state, e.g, US.TX for Texas.  To specify a
    whole continent, prepend = to any of the continent codes AF (Africa),
    AN (Antarctica), AS (Asia), EU (Europe), OC (Oceania),
    NA (North America), or SA (South America).  Append **+l** to
    just list the countries and their codes [no data extraction or plotting takes place].
    Use **+L** to see states/territories for Argentina, Australia, Brazil, Canada, China, India, Russia and the US.
    Finally, you can append **+l**\|\ **+L** to **-E**\ =\ *continent* to only list countries in that continent;
    repeat if more than one continent is requested.
    Append **+p**\ *pen* to draw polygon outlines [no outline] and
    **+g**\ *fill* to fill them [no fill].  One of **+p**\|\ **g** must be
    specified unless **-M** is in effect, in which case only one **-E** option can be given;
    append **+z** to place the country code in the segment headers via **-Z**\ *code* settings.
    Otherwise, you may repeat **-E** to give different groups of items their own pen/fill settings.
    If neither **-J** nor **-M** are set then we just print the **-R**\ *wesn* string.

Translate PyGMT docstring:

        Select painting or dumping country polygons from the Digital Chart of
        the World. This is another dataset independent of GSHHG and hence the
        **area_thresh** and **resolution** options do not apply. Append one or
        more comma-separated countries using the `2-character ISO 3166-1 alpha-2
        convention <https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2>`_. To
        select a state of a country (if available), append .state, e.g, US.TX
        for Texas.  To specify a whole continent, prepend = to any of the
        continent codes AF (Africa), AN (Antarctica), AS (Asia), EU (Europe), OC
        (Oceania), NA (North America), or SA (South America).  Append **+l** to
        just list the countries and their codes [no data extraction or plotting
        takes place]. Use **+L** to see states/territories for Argentina,
        Australia, Brazil, Canada, China, India, Russia and the US. Finally, you
        can append **+l**\|\ **+L** to **dcw**\ =\ *continent* to only list
        countries in that continent; repeat if more than one continent is
        requested. Append **+p**\ *pen* to draw polygon outlines [no outline]
        and **+g**\ *fill* to fill them [no fill].  One of **+p**\|\ **g** must
        be specified unless **-M** is in effect, in which case only one **dcw**
        option can be given; append **+z** to place the country code in the
        segment headers via **-Z**\ *code* settings. Otherwise, you may repeat
        **dcw** to give different groups of items their own pen/fill settings.
        If neither **projection** nor **-M** are set then we just print the
        **region**\ *wesn* string.

[seisman]

I'm closing the PR because translating GMT docs to PyGMT docstrings is a tough job that cannot be done in this PR.