Style AUTHORS, INPUT, OUTPUT, EXAMPLES, etc.

[kwankyu]

To make them look better.

Sample pages:

• https://deploy-preview-37614--sagemath.netlify.app/html/en/reference/probability/sage/probability/probability_distribution

• https://deploy-preview-37614--sagemath.netlify.app/html/en/reference/structure/sage/structure/formal_sum.html#formal-sums

📝 Checklist

• The title is concise and informative.
• The description explains in detail what this PR is about.
• I have linked a relevant issue or discussion.
• I have created tests covering the changes.
• I have updated the documentation accordingly.

⌛ Dependencies

[mkoeppe]

Why remove the colons?

[kwankyu]

The section titles are now in bold face, that I thought makes the colon dispensable.

Which do you like?

1. INPUT: (original style)
2. INPUT
3. INPUT:
4. INPUT

We may also style "EXAMPLES:" differently from "INPUT" and "OUTPUT". What do you think?

[kwankyu]

Or we may add when needed:

OUTPUT: a list of integers

OUTPUT

• A list ot integers
• A list of strings

This is choice (5).

[kwankyu]

I chose to go with (3) with colon. To balance, I reduced the boldness (the weight).

[kwankyu]

Experimenting with (5). Let's see.

[kwankyu]

Which do you like? Vote on your preference

1. (original style)

INPUT:

• A list ot integers
• A list of strings

2. (boldface without colon)

INPUT

• A list ot integers
• A list of strings

3. (boldface with colon)

INPUT:

• A list ot integers
• A list of strings

4. (italic)

INPUT

• A list ot integers
• A list of strings

5. (italic with colon)

INPUT:

• A list ot integers
• A list of strings

6. (boldface and colon only if there is a text in the same line with the section title)

OUTPUT: a list of integers

OUTPUT

• A list ot integers
• A list of strings

[kwankyu]

+1 for (6)

[roed314]

In 6, doesn't Input always have following text?

[videlec]

If this has to be fixed in sage, I would rather stick to something standard and existent in the Python world, namely either

• PEP 257
• or Google style (see also this sphinx documentation page)
• or Numpy style (see also this sphinx documentation page)

[kwankyu]

In 6, doesn't Input always have following text?

Sorry for being obscure. I modified the description.

[kwankyu]

If this has to be fixed in sage, I would rather stick to something standard and existent in the Python world, namely either

• PEP 257
• or Google style (see also this sphinx documentation page)
• or Numpy style (see also this sphinx documentation page)

Note that this PR is about the cosmetic change in the rendered docstring by Sphinx. The format of the source docstring doesn't change. Your suggestion is about the source format. It should be a separate PR if you are interested in it. (There is already one if you look for it.) This PR is not about that. On the other hand, I like the current format, simple and clear :-)

[tscrim]

1

Best to just keep it simple.

[egourgoulhon]

1

... for the same reason as @tscrim + the sample pages in the PR description look bad to me: the colons are gone and the section titles do appear bold in my browser (Firefox).

[github-actions]

Documentation preview for this PR (built with commit 00cd01e; changes) is ready! 🎉
This preview will update shortly after each push to this PR.

[kwankyu]

Ready for review again.

The styling to AUTHORs section is the main thing of this PR.

The stylings to INPUT, OUTOUT, etc. was dropped respecting the voting result (1). However I keep the (non-running) code for possible change in future.