fmt_docstring: Allow raw curly braces {} to avoid KeyError

[seisman]

Description of the desired feature

The @fmt_docstring decorator is responsible for inserting common docstrings into placeholders. While it works well in general, it currently raises a KeyError when encountering an undefined placeholder. For example, in #3811, we're writing equations in ReST syntax:

:math:`mantissa * 10 ^ {exponent}`

and it reports KeyError: exponent because we don't have exponent defined in COMMON_DOCSTRINGS. This requires us to escape such placeholders by writing the equation like

:math:`mantissa * 10 ^ {{exponent}}`

which is inconvenient, and sometimes we may forget to do it and then see the KeyError exception surprisingly.

Current Behavior:

• If {exponent} (or any other undefined placeholder) appears in a docstring, fmt_docstring raises a KeyError.
• To work around this, users must write {{exponent}} to ensure the curly braces are preserved in the final docstring.

Expected Behavior:

• {exponent} (or any other undefined placeholder) should be treated as a literal string unless it matches a defined common docstring key.
• When writing docstrings, we don't have to manually escape curly braces unless explicitly required.

Pros

1. No need to escape curly braces, especially for equations
2. The raw docstrings, especially math equations, are more readable

Cons

If there are any typos in common placeholder (e.g., projection typed as projecti), then the literal string {projecti} is shown in the HTML documentation. It no longer raises a KeyError exception, and we may miss the typo.

Are you willing to help implement and maintain this feature?

Yes

[seisman]

@GenericMappingTools/pygmt-maintainers Any comments on this?

[weiji14]

Yeah, it would be nice to write LaTeX style math equations directly without the double curly braces {{ }}. It's not just ReST syntax, but also MyST that uses it - https://mystmd.org/guide/math.

Sphinx does support substitutions via a | | syntax for ReST - https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions, that might be coming to MyST in some form - jupyter-book/mystmd#852. Maybe we can consider using this built-in method than complicating the @fmt_docstring decorator function further? But it will involve a lot of rewriting of the docstrings to do { } -> | | for the aliases.

[seisman]

Using substitutions | | sounds an interesting idea. As far as I know, substituions don't support multi-paragraph long texts, so it may not work as expected.