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

[Jeroen Demeyer]

On 2017-05-18 14:36, Erik Bray wrote:

I don't think you could write something that is intelligent enough to
distinguish the literals ``True``, ``False``, or ``None`` with the
word itself (which would be capitalized if beginning a sentence--not
common, but not impossible either).


Reasonable example: "None of the input vertices should be adjacent."

--
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] Poll for issue G1 a specific guideline for writing docstrings

[Erik Bray]

On Thu, May 18, 2017 at 9:19 AM, Kwankyu Lee  wrote:
>> -1
>>
>> See the first few lines of [1] where an equivalent of our ``True`` is
>> used (and therefore written in typewriter font)
>
>
> (This is perhaps my last resistance; please bear with me :-)
>
> A technical question: is it possible to set our Sphinx so that we write in a
> docstring
>
> Return True if something is False.
>
> but the True and False are rendered in tt font (or even as links as you
> suggested). Then we could avoid cluttering files with lots of double quotes
> for True, False, and None, and use them mostly for arguments.

I don't think you could write something that is intelligent enough to
distinguish the literals ``True``, ``False``, or ``None`` with the
word itself (which would be capitalized if beginning a sentence--not
common, but not impossible either).

-- 
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] Poll for issue G1 a specific guideline for writing docstrings

[Kwankyu Lee]

>
> -1 
>
> See the first few lines of [1] where an equivalent of our ``True`` is 
> used (and therefore written in typewriter font)
>

(This is perhaps my last resistance; please bear with me :-) 

A technical question: is it possible to set our Sphinx so that we write in 
a docstring

Return True if something is False.

but the True and False are rendered in tt font (or even as links as you 
suggested). Then we could avoid cluttering files with lots of double quotes 
for True, False, and None, and use them mostly for arguments.
 

-- 
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] Poll for issue G1 a specific guideline for writing docstrings

[Daniel Krenn]

On 2017-05-17 16:07, 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. 

-1

See the first few lines of [1] where an equivalent of our ``True`` is
used (and therefore written in typewriter font)

Moreover, in the note box above
Section "3.1. Constants added by the site module", it is even done
better and a link to Python's True and False is given. (+1 for linking
True, False, None to these Python sites. IMO this should be the
encouraged way also for Python's exceptions etc.)

[1] https://docs.python.org/3/library/constants.html

-- 
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.