fmt_docstrings: Support raw curly braces in docstrings using str.format_map

Author: seisman

pygmt/helpers/decorators.py

@@ -441,7 +441,21 @@ def fmt_docstring(module_func):
        - R = region
     <BLANKLINE>
     """  # noqa: D410,D411
-    filler_text = {}
+
+    class _Placeholder(dict):
+        """
+        A dict subclass that allows missing placeholders in docstrings.
+
+        Related to https://github.com/GenericMappingTools/pygmt/issues/3815.
+        """
+
+        def __missing__(self, key):
+            """
+            Return "{key}" for a missing key.
+            """
+            return "{" + key + "}"
+
+    filler_text = _Placeholder()
 
     if hasattr(module_func, "aliases"):
         aliases = ["**Aliases:**\n"]
@@ -467,8 +481,7 @@ def fmt_docstring(module_func):
     # Dedent the docstring to make it all match the option text.
     docstring = textwrap.dedent(module_func.__doc__)
 
-    module_func.__doc__ = docstring.format(**filler_text)
-
+    module_func.__doc__ = docstring.format_map(filler_text)
     return module_func