[sage-devel] Re: python3 : help needed

[John H Palmieri]

On Friday, May 19, 2017 at 3:27:54 PM UTC-7, John H Palmieri wrote:
>
>
>
> On Friday, May 19, 2017 at 2:46:15 PM UTC-7, John H Palmieri wrote:
>>
>>
>>
>> On Friday, May 19, 2017 at 9:51:46 AM UTC-7, Frédéric Chapoton wrote:
>>>
>>> Dear all,
>>>
>>> We have almost reached the state of vanilla sage building with 
>>> SAGE_PYTHON3=yes (this does not mean working !). But something seems to go 
>>> wrong, and I would like help to find and fix the current problem.
>>>
>>> So, for people that want to do something else than answering polls, you 
>>> can try the following:
>>>
>>> In a separate install of sage, on top of 8.0.beta7, apply
>>>
>>> https://trac.sagemath.org/ticket/23030 (git pull trac u/chapoton/23030)
>>>
>>> and
>>>
>>> https://trac.sagemath.org/ticket/22305 (git pull trac public/22305)
>>>
>>> then export SAGE_PYTHON3=yes
>>>
>>> and make build.
>>>
>>> This should finish succesfully, with the usual message. 
>>>
>>
>> It took me a bit more work. First I had a problem with the Sage library, 
>> which I could fix by applying #23029. Second, conway-polynomials wouldn't 
>> build because it couldn't find six.moves, so I had to change the 
>> spkg-install script to use #!/usr/bin/env sage-python23 instead of 
>> #!/usr/bin/env python. I should also point out that even when the problem 
>> is only in conway-polynomials, the build process keeps rebuilding all of 
>> sagelib, rebuilding all of the extensions. So something is not correctly 
>> detecting that the Sage library files are already built and installed.
>>
>> The docs now don't build, although now I see that you were not 
>> recommending even trying. Anyway, the error is:
>>
>> /Users/palmieri/Desktop/Sage_stuff/sage_builds/TESTING/sage-8.0.beta7/local/bin/python:
>>  
>> No module named sage_setup
>>
>> I suppose it should be calling python3 or sage-python23 instead. If we're 
>> not worrying about the docs for now, that's fine with me.
>>
>>
>> Anyway, I finally got 'make build' to work and I ran into the same 
>> problem you did. One issue is that sage-ipython is being called, and its 
>> first line is #!/usr/bin/env python, which calls python2. You can change 
>> that to sage-python23 (which calls a version of Python depending on the 
>> setting of SAGE_PYTHON3). When I do that, Sage creates a crash report, 
>> saying 
>>
>> ModuleNotFoundError: No module named 'sage.structure.sage_object'. 
>> Indeed, when I look at local/lib/python3.6/site-packages/sage/structure, 
>> there are no .so files there. This must be related to the issues that 
>> caused constant rebuilding of the Sage library. Here are some lines from 
>> the log file:
>>
>> copying build/lib.macosx-10.9-x86_64-3.6/sage/structure/
>> sage_object.cpython-36m-darwin.so -> 
>> /Users/palmieri/Desktop/Sage_stuff/sage_builds/TESTING/sage-8.0.beta7/local/lib/python3.6/site-packages/sage/structure
>>
>> and then later
>>
>> Cleaning up stale file: 
>> /Users/palmieri/Desktop/Sage_stuff/sage_builds/TESTING/sage-8.0.beta7/local/lib/python3.6/site-packages/sage/structure/
>> sage_object.cpython-36m-darwin.so
>>
>> (Why isn't it just called "sage_object.so"?)
>>
>
> The stale file issue has been discussed before: 
> https://groups.google.com/d/msg/sage-devel/W7FotQglFBs/RsnII556AwAJ. 
>

If I comment out the "self.clean_stale_files()" line from src/setup.py, 
then I still get an error, but one you might expect from Python3: 
"NameError: name 'unicode' is not defined". This comes from 
src/sage/misc/sageinspect.py:

if not isinstance(r, string_types):
return ''
elif isinstance(r, unicode):
return r.encode('utf-8', 'ignore')
else:
return r

 

>  
>
>>
>> -- 
>> John
>>
>>
>>
>>  
>>
>>> Then try ./sage
>>>
>>> For me, this fails with some traceback about not finding 
>>> sage.repl.interpreter. Can someone help to fix that please ?
>>>
>>> Frédéric
>>>
>>>

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: python3 : help needed

[John H Palmieri]

On Friday, May 19, 2017 at 2:46:15 PM UTC-7, John H Palmieri wrote:
>
>
>
> On Friday, May 19, 2017 at 9:51:46 AM UTC-7, Frédéric Chapoton wrote:
>>
>> Dear all,
>>
>> We have almost reached the state of vanilla sage building with 
>> SAGE_PYTHON3=yes (this does not mean working !). But something seems to go 
>> wrong, and I would like help to find and fix the current problem.
>>
>> So, for people that want to do something else than answering polls, you 
>> can try the following:
>>
>> In a separate install of sage, on top of 8.0.beta7, apply
>>
>> https://trac.sagemath.org/ticket/23030 (git pull trac u/chapoton/23030)
>>
>> and
>>
>> https://trac.sagemath.org/ticket/22305 (git pull trac public/22305)
>>
>> then export SAGE_PYTHON3=yes
>>
>> and make build.
>>
>> This should finish succesfully, with the usual message. 
>>
>
> It took me a bit more work. First I had a problem with the Sage library, 
> which I could fix by applying #23029. Second, conway-polynomials wouldn't 
> build because it couldn't find six.moves, so I had to change the 
> spkg-install script to use #!/usr/bin/env sage-python23 instead of 
> #!/usr/bin/env python. I should also point out that even when the problem 
> is only in conway-polynomials, the build process keeps rebuilding all of 
> sagelib, rebuilding all of the extensions. So something is not correctly 
> detecting that the Sage library files are already built and installed.
>
> The docs now don't build, although now I see that you were not 
> recommending even trying. Anyway, the error is:
>
> /Users/palmieri/Desktop/Sage_stuff/sage_builds/TESTING/sage-8.0.beta7/local/bin/python:
>  
> No module named sage_setup
>
> I suppose it should be calling python3 or sage-python23 instead. If we're 
> not worrying about the docs for now, that's fine with me.
>
>
> Anyway, I finally got 'make build' to work and I ran into the same problem 
> you did. One issue is that sage-ipython is being called, and its first line 
> is #!/usr/bin/env python, which calls python2. You can change that to 
> sage-python23 (which calls a version of Python depending on the setting of 
> SAGE_PYTHON3). When I do that, Sage creates a crash report, saying 
>
> ModuleNotFoundError: No module named 'sage.structure.sage_object'. Indeed, 
> when I look at local/lib/python3.6/site-packages/sage/structure, there are 
> no .so files there. This must be related to the issues that caused constant 
> rebuilding of the Sage library. Here are some lines from the log file:
>
> copying build/lib.macosx-10.9-x86_64-3.6/sage/structure/
> sage_object.cpython-36m-darwin.so -> 
> /Users/palmieri/Desktop/Sage_stuff/sage_builds/TESTING/sage-8.0.beta7/local/lib/python3.6/site-packages/sage/structure
>
> and then later
>
> Cleaning up stale file: 
> /Users/palmieri/Desktop/Sage_stuff/sage_builds/TESTING/sage-8.0.beta7/local/lib/python3.6/site-packages/sage/structure/
> sage_object.cpython-36m-darwin.so
>
> (Why isn't it just called "sage_object.so"?)
>

The stale file issue has been discussed before: 
https://groups.google.com/d/msg/sage-devel/W7FotQglFBs/RsnII556AwAJ. 
 

>
> -- 
> John
>
>
>
>  
>
>> Then try ./sage
>>
>> For me, this fails with some traceback about not finding 
>> sage.repl.interpreter. Can someone help to fix that please ?
>>
>> Frédéric
>>
>>

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Re: Second round poll for H2 a specific guideline for writing docstrings

[Kwankyu Lee]

This is my last attempt to save the guideline.

A Sage user has an integer X. He hit the tab key and get "X.is_prime", and 
then ask what this method does by entering "X.is_prime?". Imagine that he 
reads

(1) Return whether the integer is prime.

(2) Return whether this integer is prime.

(3) Return whether ``self`` is prime.

Which one of these is most friendly plain English answer to his question?

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: python3 : help needed

[John H Palmieri]

On Friday, May 19, 2017 at 9:51:46 AM UTC-7, Frédéric Chapoton wrote:
>
> Dear all,
>
> We have almost reached the state of vanilla sage building with 
> SAGE_PYTHON3=yes (this does not mean working !). But something seems to go 
> wrong, and I would like help to find and fix the current problem.
>
> So, for people that want to do something else than answering polls, you 
> can try the following:
>
> In a separate install of sage, on top of 8.0.beta7, apply
>
> https://trac.sagemath.org/ticket/23030 (git pull trac u/chapoton/23030)
>
> and
>
> https://trac.sagemath.org/ticket/22305 (git pull trac public/22305)
>
> then export SAGE_PYTHON3=yes
>
> and make build.
>
> This should finish succesfully, with the usual message. 
>

It took me a bit more work. First I had a problem with the Sage library, 
which I could fix by applying #23029. Second, conway-polynomials wouldn't 
build because it couldn't find six.moves, so I had to change the 
spkg-install script to use #!/usr/bin/env sage-python23 instead of 
#!/usr/bin/env python. I should also point out that even when the problem 
is only in conway-polynomials, the build process keeps rebuilding all of 
sagelib, rebuilding all of the extensions. So something is not correctly 
detecting that the Sage library files are already built and installed.

The docs now don't build, although now I see that you were not recommending 
even trying. Anyway, the error is:

/Users/palmieri/Desktop/Sage_stuff/sage_builds/TESTING/sage-8.0.beta7/local/bin/python:
 
No module named sage_setup

I suppose it should be calling python3 or sage-python23 instead. If we're 
not worrying about the docs for now, that's fine with me.


Anyway, I finally got 'make build' to work and I ran into the same problem 
you did. One issue is that sage-ipython is being called, and its first line 
is #!/usr/bin/env python, which calls python2. You can change that to 
sage-python23 (which calls a version of Python depending on the setting of 
SAGE_PYTHON3). When I do that, Sage creates a crash report, saying 

ModuleNotFoundError: No module named 'sage.structure.sage_object'. Indeed, 
when I look at local/lib/python3.6/site-packages/sage/structure, there are 
no .so files there. This must be related to the issues that caused constant 
rebuilding of the Sage library. Here are some lines from the log file:

copying 
build/lib.macosx-10.9-x86_64-3.6/sage/structure/sage_object.cpython-36m-darwin.so
 
-> 
/Users/palmieri/Desktop/Sage_stuff/sage_builds/TESTING/sage-8.0.beta7/local/lib/python3.6/site-packages/sage/structure

and then later

Cleaning up stale file: 
/Users/palmieri/Desktop/Sage_stuff/sage_builds/TESTING/sage-8.0.beta7/local/lib/python3.6/site-packages/sage/structure/sage_object.cpython-36m-darwin.so

(Why isn't it just called "sage_object.so"?)

-- 
John



 

> Then try ./sage
>
> For me, this fails with some traceback about not finding 
> sage.repl.interpreter. Can someone help to fix that please ?
>
> Frédéric
>
>

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Re: Second round poll for H2 a specific guideline for writing docstrings

[Vincent Delecroix]

On 19/05/2017 20:39, kcrisman wrote:



On Thursday, May 18, 2017 at 10:29:42 PM UTC-4, Travis Scrimshaw wrote:


Strong -1 (still)



Even though this is something confusing to newcomers, I think that I have
to agree with Travis.  That said, I don't see why one couldn't just say "if
``self`` (the lattice) is reflexive".


Much harder to read than the two versions "self" vs "the lattice"! In 
the one line description I tend to think that we can have additional 
information using "this X" rather than self, eg


   def is_prime(self):
 "Test whether this integer is prime"

versus

def is_prime(self):
"Test whether ``self`` is prime"

In the rest of the docstring, it might be a good practice to use 
``self`` especially when algorithmic considerations are given. For example


"""
Test whether this integer is prime

If ``self`` is more than 8000 bits we use some nice
heuristic from outer space.
"""

Vincent

--
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Docstring standards: new Sphinx directives? New Sphinx directions?

[kcrisman]

On Friday, May 19, 2017 at 12:04:16 AM UTC-4, Jori Mäntysalo wrote:
>
> On Thu, 18 May 2017, John H Palmieri wrote: 
>
> > .. INPUT:: 
> > 
> > We would need to add "INPUT", "OUTPUT", etc. as Sphinx directives. Then 
> we would have control over the format for the 
> > output. 


That sounds great, but might need a patch bomb or three.  I don't recommend 
using the other syntax you mentioned, for continuity purposes. 

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Second round poll for H2 a specific guideline for writing docstrings

[kcrisman]

On Thursday, May 18, 2017 at 10:29:42 PM UTC-4, Travis Scrimshaw wrote:
>
> Strong -1 (still)
>

Even though this is something confusing to newcomers, I think that I have 
to agree with Travis.  That said, I don't see why one couldn't just say "if 
``self`` (the lattice) is reflexive". 

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Google Summer of Code 2017 matroids project

[Vincent Delecroix]

Welcome on board! Do not hesitate to use this list for your questions 
relative to Sage development in general (but use trac ticket for 
specific issues concerning the code).


Vincent

On 19/05/2017 02:13, Zachary Gershkoff wrote:

Hello,

This year I will be working on the matroid and graph theory packages for
Google Summer of Code. My project will focus on expanding the list of
matroid classes available in sage, with methods to do convenient or more
efficient computations specific to the class. In particular, I'll make a
graphic matroid class, where instances will keep an associated graph in
memory. I also will try to improve the existing functionality for plotting
rank-3 matroids geometrically.

My GSoC blog is at https://picturesofmatroids.wordpress.com/ . I've already
started working on tickets such as https://trac.sagemath.org/ticket/23027
(needs review) and https://trac.sagemath.org/ticket/22559 (positive review)
so I should be ready to go once coding starts May 30th.

--Zach



--
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Second round poll for H2 a specific guideline for writing docstrings

[Vincent Delecroix]

I am following Johan: +1 to "this lattice" and +1/2 to "the lattice"

On 19/05/2017 00:20, Kwankyu Lee wrote:

Hi,

I prepared H2 revised from G2 based on your ideas and wishes. It was hard
to make a compromise from your differing opinions and reach a proposal for
the better. So this time* if I fail to get approval from most of you, the
guideline will be simply discarded.*
**
H2. Write

if the lattice is reflexive

but do not write

if ``self`` is reflexive

If you agree, flag +1; if you don't, flag -1.



--
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Second round poll for H1 a specific guideline for writing docstrings

[Vincent Delecroix]

+1

On 19/05/2017 00:17, Kwankyu Lee wrote:

Hi,

I prepared H1 revised from G1 based on your ideas and wishes. It was hard
to make a compromise from your differing opinions and reach a proposal for
the better. So this time* if I fail to get approval from most of you, the
guideline will be simply discarded.*
**
H1. Write

``True``, ``False``, ``None``

but do not write

True, False, None

If you agree, flag +1; if you don't, flag -1.




--
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Second round poll for H3 a specific guideline for writing docstrings

[Vincent Delecroix]

+1

On 19/05/2017 00:22, Kwankyu Lee wrote:

Hi,

I prepared H3 revised from G3 based on your ideas and wishes. It was hard
to make a compromise from your differing opinions and reach a proposal for
the better. So this time* if I fail to get approval from most of you, the
guideline will be simply discarded.*
**
H3. Write

Return whether the lattice is reflexive.

but do not write

Return ``True`` if the lattice is reflexive and ``False`` otherwise.


If you agree, flag +1; if you don't, flag -1.



--
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] python3 : help needed

[Frédéric Chapoton]

Dear all,

We have almost reached the state of vanilla sage building with 
SAGE_PYTHON3=yes (this does not mean working !). But something seems to go 
wrong, and I would like help to find and fix the current problem.

So, for people that want to do something else than answering polls, you can 
try the following:

In a separate install of sage, on top of 8.0.beta7, apply

https://trac.sagemath.org/ticket/23030 (git pull trac u/chapoton/23030)

and

https://trac.sagemath.org/ticket/22305 (git pull trac public/22305)

then export SAGE_PYTHON3=yes

and make build.

This should finish succesfully, with the usual message. Then try ./sage

For me, this fails with some traceback about not finding 
sage.repl.interpreter. Can someone help to fix that please ?

Frédéric

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Re: Second round poll for H5 a specific guideline for writing docstrings

[Michael Orlitzky]

On 05/19/2017 02:55 AM, david.coud...@inria.fr wrote:
> A method like `Graph().is_bipartite(certificate=False)` returns either
> ``True``or ``False`` when ``certificate==False``, or a tuple `(bool,
> dict)` when ``certificate==True``. What would be the recommended writing
> style for the output block ?

We should outlaw the practice, and anyone who enjoys using MATLAB =)

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Secondl round poll for H6 a specific guideline for writing docstrings

[Travis Scrimshaw]

On Friday, May 19, 2017 at 4:32:58 AM UTC-5, Kwankyu Lee wrote:
>
> +1
>
> In English, I understand that "foo; bar" is used if "bar" gives additional 
> information about "foo" while "foo, bar"is used to list "foo" and "bar" on 
> equal level. But I am not a native speaker...
>

Actually, that probably means you are a better judge because you spent time 
actually studying the proper methods. With that being said, being a native 
speaker, this is a correct approach. Semicolons can also be used to 
separate list items, in particular when those list items themselves contain 
commas, or connect two sentences/ideas that could be separated by a period 
(full stop) but you want to build an association between them.

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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Second round poll for H4 a specific guideline for writing docstrings

[Vincent Delecroix]

+1

On 19/05/2017 00:24, Kwankyu Lee wrote:

Hi,

I prepared H4 revised from G4 based on your ideas and wishes. It was hard
to make a compromise from your differing opinions and reach a proposal for
the better. So this time* if I fail to get approval from most of you, the
guideline will be simply discarded.*
**
H4. OUTPUT block is optional but recommended unless it is clear from the
one-line
explanation.

If you agree, flag +1; if you don't, flag -1.



--
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Re: Second round poll for H5 a specific guideline for writing docstrings

[Jori Mäntysalo]

On Fri, 19 May 2017, Sébastien Labbé wrote:


  My suggestion would be

  OUTPUT:

  - If ``certificate=True`` return only True or False.
  - If ``certificate=False`` return either
     * (True, XX), where XX is...
     * (False, XX), where XX is...
 
I think this is too much information which will overlap with the INPUT block
or even a small paragraph that goes before the INPUT block, that explains
the certificate stuff. The only thing I want to see in the OUTPUT block is
the *type* of the objects and how many of them.


I should see a whole example to be able to comment this. We can have 
longer INPUT and shorter OUTPUT, or vice versa.


--
Jori Mäntysalo

Re: [sage-devel] Second round poll for H2 a specific guideline for writing docstrings

[Johan S . H . Rosenkilde]

+1 to "this lattice" and +1/2 to "the lattice". In either case I think
it should mention in the guideline that using ``self`` is also
acceptable if the sentence would become more clear.


Kwankyu Lee writes:

> Hi,
>
> I prepared H2 revised from G2 based on your ideas and wishes. It was hard 
> to make a compromise from your differing opinions and reach a proposal for 
> the better. So this time* if I fail to get approval from most of you, the 
> guideline will be simply discarded.*  
> **
> H2. Write
>
> if the lattice is reflexive 
>
> but do not write
>
> if ``self`` is reflexive
> 
> If you agree, flag +1; if you don't, flag -1.

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Second round poll for H4 a specific guideline for writing docstrings

[Johan S . H . Rosenkilde]

+1

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Second round poll for H5 a specific guideline for writing docstrings

[Johan S . H . Rosenkilde]

> As I mentioned on the other thread, since OUTPUT is not a list of things 
> (as opposed to INPUT), I would prefer
>
> OUTPUT: tuple of lattices

+1 on this option (and hence -1 to the thread's suggestion).

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Second round poll for H1 a specific guideline for writing docstrings

[Johan S . H . Rosenkilde]

+1

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Secondl round poll for H6 a specific guideline for writing docstrings

[Johan S . H . Rosenkilde]

> H6. Write
>
> INPUT: 
>
> - ``n`` -- integer (default: 1); the number of repetition

+1. I agree with the grammatical reasons to slightly prefer ";" over ","
(but I am not a native speaker).

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Second round poll for H3 a specific guideline for writing docstrings

[Johan S . H . Rosenkilde]

+1

Kwankyu Lee writes:

> Hi,
>
> I prepared H3 revised from G3 based on your ideas and wishes. It was hard 
> to make a compromise from your differing opinions and reach a proposal for 
> the better. So this time* if I fail to get approval from most of you, the 
> guideline will be simply discarded.*  
> **
> H3. Write
>
> Return whether the lattice is reflexive.
>
> but do not write
>
> Return ``True`` if the lattice is reflexive and ``False`` otherwise.
>
> 
> If you agree, flag +1; if you don't, flag -1.

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Secondl round poll for H6 a specific guideline for writing docstrings

[Sébastien Labbé]

On Friday, May 19, 2017 at 8:55:13 AM UTC+2, Simon King wrote:
>
> Almost +1 
>
> Actually I thought this guideline has already been used, with 
> a minute difference: 
>- ``n`` -- integer (default 1), the number of repetitions 
>

+1

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Second round poll for H3 a specific guideline for writing docstrings

[Sébastien Labbé]

On Friday, May 19, 2017 at 12:22:15 AM UTC+2, Kwankyu Lee wrote:

> **
> H3.  If you agree, flag +1; if you don't, flag -1.
>

+1
 

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Second round poll for H1 a specific guideline for writing docstrings

[Sébastien Labbé]

On Friday, May 19, 2017 at 12:17:39 AM UTC+2, Kwankyu Lee wrote:
>
> H1.  If you agree, flag +1; if you don't, flag -1.
>
> +1
 

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Re: Second round poll for H5 a specific guideline for writing docstrings

[Sébastien Labbé]

>
> My suggestion would be 
>
> OUTPUT: 
>
> - If ``certificate=True`` return only True or False. 
> - If ``certificate=False`` return either 
>* (True, XX), where XX is... 
>* (False, XX), where XX is... 
>
>
>  
I think this is too much information which will overlap with the INPUT 
block or even a small paragraph that goes before the INPUT block, that 
explains the certificate stuff. The only thing I want to see in the OUTPUT 
block is the *type* of the objects and how many of them.

So in the ultra rare case of output type or length depending on some flag, 
I would go for:

OUTPUT: boolean or a 2-tuple (boolean, XX) if certificate is True

In all other case and in particular for what is suggested for the guideline 
which will apply to almost all cases, I would go +1 for H5 (or +1 for 
Jeroen's shorter suggestion. I don't really mind actually).

Sébastien


-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Second round poll for H5 a specific guideline for writing docstrings

[Kwankyu Lee]

+1

H5 is intended to be conforming with "INPUT:" block. 

The above example is somewhat misleading. If the output is just a "tuple of 
lattices" (without long additional explanation), then the entire OUTPUT 
block can be omitted since the one-liner can be "Return a tuple of lattices 
that ". 

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Second round poll for H2 a specific guideline for writing docstrings

[Kwankyu Lee]

>
> Here is my opinion. But a metaquestion: Why can't someone (like Kwankyu) 
> just got direct emails and make a summary? 
>

Hmm. Just to make the result of the voting transparent to everyone.

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Re: Second round poll for H5 a specific guideline for writing docstrings

[Jori Mäntysalo]

On Thu, 18 May 2017, david.coud...@inria.fr wrote:


A method like `Graph().is_bipartite(certificate=False)` returns either
``True``or ``False`` when ``certificate==False``, or a tuple `(bool, dict)`
when ``certificate==True``. What would be the recommended writing style for
the output block ?


My suggestion would be

OUTPUT:

- If ``certificate=True`` return only True or False.
- If ``certificate=False`` return either
  * (True, XX), where XX is...
  * (False, XX), where XX is...

and when there is only one-way certificate,

OUTPUT:

- If ``certificate=True`` return only True or False.
- If ``certificate=False`` return either (True, None) or (False, XX),
  where XX is...

--
Jori Mäntysalo

[sage-devel] Re: Secondl round poll for H6 a specific guideline for writing docstrings

[Kwankyu Lee]

+1

In English, I understand that "foo; bar" is used if "bar" gives additional 
information about "foo" while "foo, bar"is used to list "foo" and "bar" on 
equal level. But I am not a native speaker...

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Second round poll for H4 a specific guideline for writing docstrings

[Kwankyu Lee]

+1

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Second round poll for H3 a specific guideline for writing docstrings

[Kwankyu Lee]

+1

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Second round poll for H2 a specific guideline for writing docstrings

[Kwankyu Lee]

+1

The point is that "the lattice" (or a slight variant "this lattice") is 
officially recommended than "``self``".

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Second round poll for H2 a specific guideline for writing docstrings

[Jori Mäntysalo]

On Fri, 19 May 2017, Kwankyu Lee wrote:


Hi Jori,
 
H2. Write

if the lattice is reflexive


  +1


It is very important that you give this vote directly to the thread

Basically the number of votes that it gets will determine whether the
guideline will be put into the developer manual.


Here is my opinion. But a metaquestion: Why can't someone (like Kwankyu) 
just got direct emails and make a summary?


It is of course different when I have untold arguments to tell, not just 
+1 or -1.


--
Jori Mäntysalo

[sage-devel] Re: Second round poll for H1 a specific guideline for writing docstrings

[Kwankyu Lee]

+1

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Second round poll for H5 a specific guideline for writing docstrings

[chris wuthrich]

-1 

I am with Jeroen on this one.


On Thursday, 18 May 2017 23:25:41 UTC+1, Kwankyu Lee wrote:
>
> Hi,
>
> I prepared H5 revised from G5 based on your ideas and wishes. It was hard 
> to make a compromise from your differing opinions and reach a proposal for 
> the better. So this time* if I fail to get approval from most of you, the 
> guideline will be simply discarded.*  
> **
> H5. Write
>
> OUTPUT: 
>
> - tuple of lattices
>
> Note the leading hyphen and no period at the end. If the output consists 
> of several items, add each starting with a hyphen.
> 
> If you agree, flag +1; if you don't, flag -1.
>

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Re: Secondl round poll for H6 a specific guideline for writing docstrings

[Erik Bray]

On Fri, May 19, 2017 at 8:49 AM, Simon King  wrote:
> Almost +1
>
> Actually I thought this guideline has already been used, with
> a minute difference:
>- ``n`` -- integer (default 1), the number of repetitions
>
> (so, "default" instead of "default:" and ")," instead of ");",
> since "path connected" punctuation marks are better than disconnected
> ones.

I find this less readable, and also less correct in how the
punctuation is used, but this is entirely subjective.

+1 to the original proposal.

> Actually I slightly prefer the modification that I stated.
>
> Rationale for the suggested modification: In some languages such
> as French, there is a mandatory blank space before any disconnected
> punctuation mark ("foo ; bar", foo : bar", "foo ? bar" "foo ! bar").
> But we write English, where this additional blank space is considered
> a typo.
>
> Hence, a guideline that avoids disconnected puncuation marks whenever
> possible helps to avoid spelling errors.
>
> Best regards,
> Simon
>
> On 2017-05-18, Kwankyu Lee  wrote:
>> Hi,
>>
>> I prepared H6 from your comments on the style of INPUT block. It was hard
>> to make a compromise from your differing opinions and reach a proposal for
>> the better. So this time* if I fail to get approval from most of you, the
>> guideline will be simply discarded.*
>> **
>> H6. Write
>>
>> INPUT:
>>
>> - ``n`` -- integer (default: 1); the number of repetition
>>
>> 
>> If you agree, flag +1; if you don't, flag -1.
>>
>
> --
> 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 post to this group, send email to sage-devel@googlegroups.com.
> Visit this group at https://groups.google.com/group/sage-devel.
> For more options, visit https://groups.google.com/d/optout.

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Second round poll for H5 a specific guideline for writing docstrings

[Daniel Krenn]

On 2017-05-19 08:57, Jeroen Demeyer wrote:
> As I mentioned on the other thread, since OUTPUT is not a list of things
> (as opposed to INPUT), I would prefer
> 
> OUTPUT: tuple of lattices

+1 for this option

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Second round poll for H4 a specific guideline for writing docstrings

[Daniel Krenn]

On 2017-05-19 00:24, Kwankyu Lee wrote:
> I prepared H4 revised from G4 based on your ideas and wishes. It was
> hard to make a compromise from your differing opinions and reach a
> proposal for the better. So this time_ if I fail to get approval from
> most of you, the guideline will be simply discarded._/  /
> //
> H4. OUTPUT block is optional but recommended unless it is clear from the
> one-line 
> explanation.
> 
> If you agree, flag +1; if you don't, flag -1.

+1

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Second round poll for H3 a specific guideline for writing docstrings

[Daniel Krenn]

On 2017-05-19 00:22, Kwankyu Lee wrote:
> I prepared H3 revised from G3 based on your ideas and wishes. It was
> hard to make a compromise from your differing opinions and reach a
> proposal for the better. So this time_ if I fail to get approval from
> most of you, the guideline will be simply discarded._/  /
> //
> H3. Write
> 
> |
> Returnwhether the lattice isreflexive.
> |
> 
> but do not write
> 
> |
> Return``True``ifthe lattice isreflexive and``False``otherwise.
> |

+1

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Second round poll for H2 a specific guideline for writing docstrings

[Daniel Krenn]

On 2017-05-19 00:20, Kwankyu Lee wrote:
> Hi,
> 
> I prepared H2 revised from G2 based on your ideas and wishes. It was
> hard to make a compromise from your differing opinions and reach a
> proposal for the better. So this time_ if I fail to get approval from
> most of you, the guideline will be simply discarded._/  /
> //
> H2. Write
> 
> |
> if the lattice is reflexive
> |

In the oneline description it could be "if *this* lattice is reflexive"
as well, as we talk about a method of this lattice.

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Re: Second round poll for H1 a specific guideline for writing docstrings

[Daniel Krenn]

On 2017-05-19 08:35, Simon King wrote:
> PS, to the +1 given earlier: I suggest that one should also write `f(x)`
> instead of f(x).

+1

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Second round poll for H1 a specific guideline for writing docstrings

[Daniel Krenn]

On 2017-05-19 00:17, Kwankyu Lee wrote:
> I prepared H1 revised from G1 based on your ideas and wishes. It was
> hard to make a compromise from your differing opinions and reach a
> proposal for the better. So this time_if I fail to get approval from
> most of you, the guideline will be simply discarded._/  /
> //
> H1. Write
> 
> |
> ``True``,``False``,``None``
> |
> 
> but do not write
> 
> |
> True,False,None
> |

+1


-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Poll for issue G4 a specific guideline for writing docstrings

[Simon King]

X on itself

-1 in combination with G3. Namely, in G3 you want that the one-line
description does not specify the output clearly, and in G4 you want
that a more-than-one-line description of the output is missing as
well. And that would be desastrous.


On 2017-05-17, Kwankyu Lee  wrote:
> We do a poll for adopting an official guideline for docstrings (see 
> https://trac.sagemath.org/ticket/23017)
> 
> G4. OUTPUT block is optional
> 
> The developer manual says OUTPUT block is not optional. But I think the 
> first statement of the docstring "Return an object ..." already describes 
> what is output. Hence usually the OUTPUT block is redundant and is needed 
> only when more explanation about the returned object is necessary.
>
> If you agree, flag +1; if you disagree, flag -1; if you want to leave it as 
> it is, flag X.
>

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Second round poll for H3 a specific guideline for writing docstrings

[Simon King]

+1

On 2017-05-18, Kwankyu Lee  wrote:
> Hi,
>
> I prepared H3 revised from G3 based on your ideas and wishes. It was hard 
> to make a compromise from your differing opinions and reach a proposal for 
> the better. So this time* if I fail to get approval from most of you, the 
> guideline will be simply discarded.*  
> **
> H3. Write
>
> Return whether the lattice is reflexive.
>
> but do not write
>
> Return ``True`` if the lattice is reflexive and ``False`` otherwise.
>
> 
> If you agree, flag +1; if you don't, flag -1.
>

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Re: Poll for issue G5 a specific guideline for writing docstrings

[Thierry]

On Fri, May 19, 2017 at 06:33:35AM +, Simon King wrote:
> +1
> 
> Here I like that the typesetting is uniform and does not distinguish
> between functions with a single return type and functions with multiple
> return types.

+1. Note that some (actually many) methods have a single input, and it
does not hurt to start with a dash there. It is also easier to remember
when writing doctests.

Ciao,
Thierry



 
> On 2017-05-17, Kwankyu Lee  wrote:
> > We do a poll for adopting an official guideline for docstrings (see 
> > https://trac.sagemath.org/ticket/23017)
> > 
> > G5. Write
> >
> > OUTPUT:
> >
> > - lattice
> >
> >
> > but do not write
> >
> > OUTPUT:
> >
> > lattice
> >
> > 
> > The development manual says a hyphen is optional. But  for consistency, we 
> > need to settle down on either style.
> >
> > If you agree, flag +1; if you disagree and want it reversed, flag -1; if 
> > you think we do not need this guideline, flag X. 
> >
> 
> -- 
> 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 post to this group, send email to sage-devel@googlegroups.com.
> Visit this group at https://groups.google.com/group/sage-devel.
> For more options, visit https://groups.google.com/d/optout.

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Second round poll for H5 a specific guideline for writing docstrings

[Simon King]

+1

On 2017-05-18, Kwankyu Lee  wrote:
> Hi,
>
> I prepared H5 revised from G5 based on your ideas and wishes. It was hard 
> to make a compromise from your differing opinions and reach a proposal for 
> the better. So this time* if I fail to get approval from most of you, the 
> guideline will be simply discarded.*  
> **
> H5. Write
>
> OUTPUT: 
>
> - tuple of lattices
>
> Note the leading hyphen and no period at the end. If the output consists of 
> several items, add each starting with a hyphen.
> 
> If you agree, flag +1; if you don't, flag -1.
>

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Poll for issue G5 a specific guideline for writing docstrings

[Simon King]

+1

Here I like that the typesetting is uniform and does not distinguish
between functions with a single return type and functions with multiple
return types.

On 2017-05-17, Kwankyu Lee  wrote:
> We do a poll for adopting an official guideline for docstrings (see 
> https://trac.sagemath.org/ticket/23017)
> 
> G5. Write
>
> OUTPUT:
>
> - lattice
>
>
> but do not write
>
> OUTPUT:
>
> lattice
>
> 
> The development manual says a hyphen is optional. But  for consistency, we 
> need to settle down on either style.
>
> If you agree, flag +1; if you disagree and want it reversed, flag -1; if 
> you think we do not need this guideline, flag X. 
>

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Second round poll for H5 a specific guideline for writing docstrings

[Jeroen Demeyer]

As I mentioned on the other thread, since OUTPUT is not a list of things 
(as opposed to INPUT), I would prefer


OUTPUT: tuple of lattices

--
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Second round poll for H5 a specific guideline for writing docstrings

[David . Coudert]

A method like `Graph().is_bipartite(certificate=False)` returns either 
``True``or ``False`` when ``certificate==False``, or a tuple `(bool, dict)` 
when ``certificate==True``. What would be the recommended writing style for 
the output block ?


-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Secondl round poll for H6 a specific guideline for writing docstrings

[Simon King]

Almost +1

Actually I thought this guideline has already been used, with
a minute difference:
   - ``n`` -- integer (default 1), the number of repetitions

(so, "default" instead of "default:" and ")," instead of ");",
since "path connected" punctuation marks are better than disconnected
ones.

Actually I slightly prefer the modification that I stated.

Rationale for the suggested modification: In some languages such
as French, there is a mandatory blank space before any disconnected
punctuation mark ("foo ; bar", foo : bar", "foo ? bar" "foo ! bar").
But we write English, where this additional blank space is considered
a typo.

Hence, a guideline that avoids disconnected puncuation marks whenever
possible helps to avoid spelling errors.

Best regards,
Simon

On 2017-05-18, Kwankyu Lee  wrote:
> Hi,
>
> I prepared H6 from your comments on the style of INPUT block. It was hard 
> to make a compromise from your differing opinions and reach a proposal for 
> the better. So this time* if I fail to get approval from most of you, the 
> guideline will be simply discarded.*  
> **
> H6. Write
>
> INPUT: 
>
> - ``n`` -- integer (default: 1); the number of repetition
>
> 
> If you agree, flag +1; if you don't, flag -1.
>

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Second round poll for H2 a specific guideline for writing docstrings

[Simon King]

X

I still cannot give a clear +1 or -1 to the current suggestion, as
it goes into the right direction but isn't flexible enough.

I'd rather suggest:
  H2.
  Write "if the lattice is reflexive" unless a technical expression
  such as "if ``self`` is reflexive" is more easy to understand.

It really cannot be more than a rule of thumb.

On 2017-05-18, Kwankyu Lee  wrote:
> Hi,
>
> I prepared H2 revised from G2 based on your ideas and wishes. It was hard 
> to make a compromise from your differing opinions and reach a proposal for 
> the better. So this time* if I fail to get approval from most of you, the 
> guideline will be simply discarded.*  
> **
> H2. Write
>
> if the lattice is reflexive 
>
> but do not write
>
> if ``self`` is reflexive
> 
> If you agree, flag +1; if you don't, flag -1.
>

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Second round poll for H4 a specific guideline for writing docstrings

[Simon King]

+1

On 2017-05-18, Kwankyu Lee  wrote:
> Hi,
>
> I prepared H4 revised from G4 based on your ideas and wishes. It was hard 
> to make a compromise from your differing opinions and reach a proposal for 
> the better. So this time* if I fail to get approval from most of you, the 
> guideline will be simply discarded.*  
> **
> H4. OUTPUT block is optional but recommended unless it is clear from the 
> one-line 
> explanation.
> 
> If you agree, flag +1; if you don't, flag -1.
>

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Second round poll for H1 a specific guideline for writing docstrings

[Simon King]

PS, to the +1 given earlier: I suggest that one should also write `f(x)`
instead of f(x).

On 2017-05-18, Kwankyu Lee  wrote:
> Hi,
>
> I prepared H1 revised from G1 based on your ideas and wishes. It was hard 
> to make a compromise from your differing opinions and reach a proposal for 
> the better. So this time* if I fail to get approval from most of you, the 
> guideline will be simply discarded.*  
> **
> H1. Write 
>
> ``True``, ``False``, ``None``
>
> but do not write 
>
> True, False, None
> 
> If you agree, flag +1; if you don't, flag -1.
>
>

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Second round poll for H1 a specific guideline for writing docstrings

[Simon King]

+1

On 2017-05-18, Kwankyu Lee  wrote:
> Hi,
>
> I prepared H1 revised from G1 based on your ideas and wishes. It was hard 
> to make a compromise from your differing opinions and reach a proposal for 
> the better. So this time* if I fail to get approval from most of you, the 
> guideline will be simply discarded.*  
> **
> H1. Write 
>
> ``True``, ``False``, ``None``
>
> but do not write 
>
> True, False, None
> 
> If you agree, flag +1; if you don't, flag -1.
>
>

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Poll for issue G3 a specific guideline for writing docstrings

[Simon King]

-1, and very strongly -1.

Reason:

On 2017-05-17, Kwankyu Lee  wrote:
> G3. Write (1) 
>
> Return True if the lattice is reflexive.

This leaves open what the function returns if it is not reflexive.
None? False? A certificate that proves that it isn't reflexive?

> but do not write (2)
>
> Return True if the lattice is reflexive and False otherwise.

This is one clear way to say what is returned.

> nor (3)
>
> Return whether the lattice is reflexive.

This is another clear and actually very elegant way to say what
is returned.

> nor (4)
>
> Test if the lattice is reflexive.

Here I agree that this is not clear enough. Does it return
``None`` if the lattice is reflexive and raises an error otherwise?

Summary: I believe the short one-line description should be
as clear as possible in a one-liner. It *is* possible to be concise
in this case ("Return whether the lattice is reflexive"), and thus
one *should* be concise.

Cheers,
Simon

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Poll for issue G2 a specific guideline for writing docstrings

[Simon King]

X

In some context, the technical term ``self`` might be easier to 
understand (for someone who knows python...) than natural language,
in other context it may be the other way around

Maybe +1 as a rule of thumb, but -1 as a strict rule.

On 2017-05-17, Kwankyu Lee  wrote:
> We do a poll for adopting an official guideline for docstrings (see 
> https://trac.sagemath.org/ticket/23017)
> 
> G2. Write
>
> if the lattice is reflexive ...
>
> but don't write
>
> if ``self`` is reflexive ...
>
> 
> If you agree, flag +1; if you disagree and want it reversed, flag -1; if 
> you think we do not need this guideline, flag X.
>

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Poll for issue G1 a specific guideline for writing docstrings

[Simon King]

-1, for reasons that have already been explained by others. Generally,
any reference to a programmatical object should be typographically 
distinguished from normal text. Hence, it should be
"Let `f(x)` be the function that returns ``True`` if `x>0` and
 ``False`` otherwise."
but not
"Let f(x) be the function that returns True if x>0 and False
 otherwise."

Cheers,
Simon


On 2017-05-17, Kwankyu Lee  wrote:
> We do a poll for adopting an official guideline for docstrings 
> (see https://trac.sagemath.org/ticket/23017)
> 
> G1. Write 
>  
> Return True if something is true.
>
> but do not write 
>
> Return ``True`` if something is true.
>
> The same applies to `False` and `None`
> 
> If you agree, flag +1; if you disagree and want it reversed, flag -1; if 
> you think we do not need this guideline, flag X. 
>

-- 
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 post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.