Recommend r"""docstring""" over """docstring"""

[MareoRaft]

The general conventions webpage https://doc.sagemath.org/html/en/developer/coding_basics.html#latex-typesetting says that both docstring syntaxes (r"""docstring""" and """docstring""") are valid (which is true), but fails to recommend one over the other.

Since it is a conventions webpage, I think it is appropriate to recommend r"""docstring""" over the latter here. The r convention is nicer because you don't need double backslashes in latex code, which is shorter and makes it easier to copy latex code from docstrings to a latex document and vice-versa. Moreover, the webpage says that we follow the PEP257 conventions (https://www.python.org/dev/peps/pep-0257/) which themselves say 'Use r"""raw triple double quotes""" if you use any backslashes in your docstrings.'

Happy to make the changes myself once everyone is on board.

Component: documentation

Keywords: convention, raw

Author: Matthew Lancellotti

Issue created by migration from https://trac.sagemath.org/ticket/25998

[bgillesp]

comment:1

Seems like a potentially good suggestion, but to clarify, do you think that this should be only in reference to docstrings containing LaTeX commands (the subsection linked in the description), or do you think it should be a universal recommendation for all docstrings?

If for all docstrings, this seems like a modestly significant convention change (though still possibly a good one), as usage of raw versus non-raw docstrings is all over the place in Sage currently. On the technical side, specifying raw docstrings would sacrifice the ability to use quoted characters, although I imagine this is not a frequently used feature in Sage docstrings.

Personally I'm happiest with "pythonic" conventions that specify a single correct manner of doing something, as long as it doesn't impose undue technical restrictions, so a universal recommendation for the r"""docstring""" convention sounds like a positive tweak to me. Interested what other more experienced developers think of this.