On Fri, Apr 30, 2021 at 6:57 AM Larry Hastings <larry@hastings.org> wrote:Function and class names should not be followed by parentheses, unless demonstrating an example call.Oh, I love putting parentheses when mentionning a function: "foo() now does thigs new thing". Also, I like to use :func:`foo` Sphinx markup to add a link in the changelog, and Sphinx adds parentheses for me *but* I don't add parentheses :-)
I do too, and I definitely do that when I write emails, .txt files, and so on. But--as you point out--Sphinx adds them for you. NEWS blurbs should be written in CPython-docs-compatible ReST, and that includes using :func:`foo` to refer to a function called foo. Sphinx will turn this into a hyperlink to the definition of foo in the docs if it knows where it is; :func:`inspect.signature` and :func:`getattr` both work great.
I'm still not sure what markup (if any) to use for Git checkins.
On Github I know to use Markdown, and they provide a Markdown edit
box. But should I use Markdown when I use "git commit" at the
command-line? And why am I bringing this up now? Surely this
will only serve to fragment the conversation and confuse the
larger issue.
Cheers,
/arry