escape-sequence-in-docstring
Bug description / feature request:
Many docstrings in struphy contain (single) backslashes, which produces warnings like this:
> struphy --refresh-models
Collecting available models ...
/raven/u/maxlin/git_repos/struphy/src/struphy/feec/preconditioner.py:394: SyntaxWarning: invalid escape sequence '\h'
"""
/raven/u/maxlin/git_repos/struphy/src/struphy/feec/preconditioner.py:700: SyntaxWarning: invalid escape sequence '\h'
"""
/raven/u/maxlin/git_repos/struphy/src/struphy/feec/preconditioner.py:732: SyntaxWarning: invalid escape sequence '\h'
"""
Done.
Example from pipeline: https://gitlab.mpcdf.mpg.de/struphy/struphy/-/jobs/3170959/viewer#L948
Error description on ruff: https://docs.astral.sh/ruff/rules/escape-sequence-in-docstring/
Proposed solution:
PEP 257 recommends the use of raw strings (i.e., r"""raw triple double quotes"""
) for docstrings that include backslashes.
This is also discussed here (specifically related to including latex in the docstring to be parsed by sphinx, the proposed solution is to use raw strings.
From sphinx documentation:
Keep in mind that when you put math markup in Python docstrings read by
autodoc
, you either have to double all backslashes, or use Python raw strings (r"raw"
).