Clarify when to mark up numeric literals

[erlend-aasland]

The current devguide recommendations reads:

backquotes: ``text`` for code samples, variables, and literals.

Earlier, I've been corrected to use double backticks when marking up literals. Example PR remark:

• https://github.com/python/cpython/pull/92790#discussion_r873084545

Recently, I've seen other styles enforced:

• https://github.com/python/cpython/pull/118068#discussion_r1577959071

Perhaps we need a clarification, possibly with good/bad examples?

[Lincoln-developer]

Hey I would love to work on this, I see there a couple of discussions that have been going on with associated PRs, may be I could first look at those and for any other details I must know on this, @erlend-aasland kindly guide.

[erlend-aasland]

Hey I would love to work on this [...]

Thanks! I believe we need to discuss this a little bit more before we can propose actual changes to the devguide. We need to agree what to put in the "good" section and what to put in the "bad" section. This implies more discussion needs to take place first.

[Lincoln-developer]

Thanks for this response, let me look at another issue.

[ezio-melotti]

My rule of thumb is that numbers should be marked as literals if they refer to values in the code (either actually written as literals or assigned/calculated/returned), e.g.:

• "The function will return 0 or 1."
• "The default value is 42."
• "math.pi is defined as equal to 3.14159."

When the number doesn't directly refer to a value in the code, the literal markup can be omitted, e.g.:

• "A week is defined as 7 days."
• "The mathematical constant π (with value 3.14159) is defined in the math module."
• "The result has already been multiplied by 1000."

Sometimes the difference is subtle though. For example, if you are suggesting the reader to multiply the result by 1000 or talking about the operation done by a specific function, you might want to use a literal. However if the calculation already happened or if the focus is about the calculation itself and not the implementation that executes it, then you don't necessarily need to.

In some ambiguous cases and especially with lists/tables, marking them as literals might also help the values stand out more (which might be desirable or not) or be easier to scan/compare. As always, use your best judgment in order to make the docs as clear and readable as possible.

FWIW the same applies to strings or other literals. For example, you can talk about "version 1.2.3" in general but "version 1.2.3" if it's returned by a function, assigned to a variable, or even used in a file like requirements.txt, or you can say that "store is the default action of argparse.add_argument", and that "it will store the value passed from the CLI".