[sage-devel] Re: Docstring Formatting Question: Bullet Points
As a fruit of this discussion, I made https://trac.sagemath.org/ticket/34348 Please review. -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/sage-devel/507281d4-96e1-4140-8164-7a5db7e4d3e9n%40googlegroups.com.
[sage-devel] Re: Docstring Formatting Question: Bullet Points
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 On Wednesday, July 13, 2022 at 12:39:42 PM UTC+9 Kwankyu Lee wrote: > 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. > > > -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/sage-devel/ddd430bf-ebdd-45a7-98c6-c2611405cf70n%40googlegroups.com.
[sage-devel] Re: Docstring Formatting Question: Bullet Points
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. -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/sage-devel/a298b834-3660-4c48-b2cc-55c774dfa166n%40googlegroups.com.
[sage-devel] Re: Docstring Formatting Question: Bullet Points
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. On Tuesday, July 12, 2022 at 6:53:23 PM UTC-7 Kwankyu Lee wrote: > 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). > > > > > > -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/sage-devel/71b22626-9880-4f1d-931e-42746aefb593n%40googlegroups.com.
[sage-devel] Re: Docstring Formatting Question: Bullet Points
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). -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/sage-devel/0daf4fdc-eebf-4bfd-adc0-4233cbb54127n%40googlegroups.com.
Re: [sage-devel] Re: Docstring Formatting Question: Bullet Points
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 -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/sage-devel/Yszde1dU9tjFYA/J%40icerm-dld.
[sage-devel] Re: Docstring Formatting Question: Bullet Points
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. 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: > > 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 > > -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/sage-devel/6464b847-1e5e-435e-81c6-3245dbc6ec9an%40googlegroups.com.
