Docstring Formatting Question: Bullet Points

[Travis Scrimshaw]

Right now there are two conventions throughout Sage for bullet points (and similar things). Someone has been systematically trying to change everything to one convention (which I am opposed to). However, we as a community have not had a discussion about this as far as I am aware (I believe also changing the example doc page at some point). I figured we should have this conversion now.

The question is this: Should there be blanklines between bullet points:

Pros (these are the ones I can see, but I am biased):

- It makes it more clear what bullet point is which.

- It could be easier to read as it looks less like a big paragraph of text.

Cons:

- IMO it looks really bad when there are few bullet points and they are really short.

- I find it harder to separate bullet points from non-bullet points, especially when

  separated by single lines

  * This includes sublists, which must have a blank line before/after them (just like normal lists).

- It makes it more clear that these bullet points should be thought of as a single

  collection.

- Because blanklines separates a list from the body of text, it makes it seem like

  the bullet points are each their own list of single items.

Note that this does not change the compiled doc, but I typically am not looking at that.

What is your opinions? I think it is clear that I am for no blanklines between bullet points.

Best,

Travis

[Matthias Koeppe]

In https://trac.sagemath.org/ticket/30448, I propose to add a linting tool for our docstrings.

I haven't checked whether it has an opinion on the style question that you asked (I don't), 

but I have already found (and fixed) some mistakes in the markup in some files using it.

[David Lowry-Duda]

>On Monday, July 11, 2022 at 4:57:39 PM UTC-7 Travis Scrimshaw wrote:
>
> Right now there are two conventions throughout Sage for bullet points (and
> similar things). Someone has been systematically trying to change
> everything to one convention (which I am opposed to). However, we as a
> community have not had a discussion about this as far as I am aware (I
> believe also changing the example doc page at some point). I figured we
> should have this conversion now.
>
> The question is this: Should there be blanklines between bullet

> points?

I am content with continuing to allow both spaced lists with newlines
and tight lists without newlines. Sage follows sphinx here, and sphinx
follows rst (as in the spec [1]).

[1]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bullet-lists

On Mon, Jul 11, 2022 at 06:57:05PM -0700, Matthias Koeppe wrote:
>In https://trac.sagemath.org/ticket/30448, I propose to add a linting tool
>for our docstrings. I haven't checked whether it has an opinion on the
>style question that you asked (I don't), but I have already found (and
>fixed) some mistakes in the markup in some files using it.

I've used flake8-rst-docstrings before and it also allows both tight and
loose list syntax by default. I don't think there is a way to choose one
style over the other.

- DLD

[Kwankyu Lee]

Bullet points are used in sage mainly in two places:

(1) AUTHORS section in the doc string of a file

(2) INPUTS section in the doc string of a class or function definition

In (1),  we usually look from the top to the bottom. This list may get longer and longer. So no blank line between points seems better.

In (2),  each argument ``arg``: is explained in a few sentences and easily takes more than one line. A blank line between arguments helps separate explanations for different arguments.

So I am +1 to no blank line to (1) and one blank line to (2).  

[John H Palmieri]

I am "no" to having a Sage policy dictating blank lines, and I am also "no" to having a policy dictating no blank lines. As Kwankyu Lee points out, sometimes a blank line is useful, sometimes it isn't. We should leave it up to the judgment of each individual developer.

[Kwankyu Lee]

On Wednesday, July 13, 2022 at 12:13:28 PM UTC+9 John H Palmieri wrote:

I am "no" to having a Sage policy dictating blank lines, and I am also "no" to having a policy dictating no blank lines. 

We do have conventions in the developer manual by which sage developers are "dictated". Specifically the blank line convention is suggested by Examples in the developer manual: 

https://doc.sagemath.org/html/en/developer/coding_basics.html#headings-of-sage-library-code-files

So perhaps Travis wants to revise the Examples if we reach to a consensus.

 

[Travis Scrimshaw]

I don't think we should mandate things so much, but it would be good to have a general policy about this. For example, we have a policy about error messages, but this is not absolute. In particular, this is about breaking ties when an author is doing something that a reviewer dislikes. I don't think effectively telling the community they can do whatever they like is so useful. (I suspect Frédéric could say a few words about this will all of the changes he has been doing to standardizing much of the code and documentation.) We should also be cognizant of the what is in the developer's manual can easily be interpreted as our convention choices/general policies (and has sometimes been referenced by reviewers in this manner).

Best,

Travis

[Kwankyu Lee]

As a fruit of this discussion, I made

https://trac.sagemath.org/ticket/34348

Please review.