-
Notifications
You must be signed in to change notification settings - Fork 234
Description
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_docstringraises 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
- No need to escape curly braces, especially for equations
- 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