Docs: Symbols and `self`

[Jori Mäntysalo]

More on docstrings:

"The Frattini sublattice `\Phi(L)` is the intersection - -" vs. "Returns
the Frattini subgroup of ``self``. The Frattini - -".

1) Should we include symbols in docstrings? I.e. add \otimes to
ordinal_product() of posets, as used in Enumerative combinatorics?

2) What about `self` in docstrings? I have avoided it, as was suggested to
me maybe a year ago. I write for example "Return True if the poset is
connected - -", i.e. "the poset" instead of "``self``".

--
Jori Mäntysalo

[Eric Gourgoulhon]

Hi,

Le vendredi 25 septembre 2015 08:45:34 UTC+2, Jori Mäntysalo a écrit :

More on docstrings:

"The Frattini sublattice `\Phi(L)` is the intersection - -" vs. "Returns
the Frattini subgroup of ``self``. The Frattini - -".

1) Should we include symbols in docstrings? I.e. add \otimes to
ordinal_product() of posets, as used in Enumerative combinatorics?

IMHO, yes. They are nicely rendered in the html documentation, either in the
notebook or in the reference manual pages.  The only trouble is of the course
the ?-help in the console mode, but this seems a minor issue since we may
assume that most users understand LaTeX.

2) What about `self` in docstrings? I have avoided it, as was suggested to
me maybe a year ago. I write for example "Return True if the poset is
connected - -", i.e. "the poset" instead of "``self``".

There was a discussion about this some time ago:
https://groups.google.com/d/msg/sage-devel/58RUzV32vI0/rf4Mldr60JkJ
and the conclusion was that we should avoid to use ``self`` in the documentation.
Indeed, for a new user, not very familiar of Python, having ``self`` in the output
of the ?-help can be disturbing. 

Best wishes,

Eric.

[William Stein]

On Fri, Sep 25, 2015 at 4:38 AM, Eric Gourgoulhon
<egourg...@gmail.com> wrote:
> Hi,
>
> Le vendredi 25 septembre 2015 08:45:34 UTC+2, Jori Mäntysalo a écrit :
>>
>> More on docstrings:
>>
>> "The Frattini sublattice `\Phi(L)` is the intersection - -" vs. "Returns
>> the Frattini subgroup of ``self``. The Frattini - -".
>>
>> 1) Should we include symbols in docstrings? I.e. add \otimes to
>> ordinal_product() of posets, as used in Enumerative combinatorics?
>
>
> IMHO, yes. They are nicely rendered in the html documentation, either in the
> notebook or in the reference manual pages. The only trouble is of the
> course
> the ?-help in the console mode, but this seems a minor issue since

> we may assume that most users understand LaTeX.

This is a questionable assumption. Numerical most users of Sage are
undergraduates, and most undergraduates don't know about LaTeX.

The mission statement of Sage is also to be a viable alternative to
Maple, Mathematica, Matlab, and Magma, and those systems definitely
aspire to be undergraduate friendly.

I wonder if there are latex --> ascii art converters (?) -- maybe the
command line help could run text through that?

William

>
>>
>> 2) What about `self` in docstrings? I have avoided it, as was suggested to
>> me maybe a year ago. I write for example "Return True if the poset is
>> connected - -", i.e. "the poset" instead of "``self``".
>
>
>
> There was a discussion about this some time ago:
> https://groups.google.com/d/msg/sage-devel/58RUzV32vI0/rf4Mldr60JkJ
> and the conclusion was that we should avoid to use ``self`` in the
> documentation.
> Indeed, for a new user, not very familiar of Python, having ``self`` in the
> output
> of the ?-help can be disturbing.
>
> Best wishes,
>
> Eric.
>

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



--
William (http://wstein.org)

[John H Palmieri]

On Friday, September 25, 2015 at 7:47:23 AM UTC-7, William wrote:

On Fri, Sep 25, 2015 at 4:38 AM, Eric Gourgoulhon
<egourg...@gmail.com> wrote:
> Hi,
>
> Le vendredi 25 septembre 2015 08:45:34 UTC+2, Jori Mäntysalo a écrit :
>>
>> More on docstrings:
>>
>> "The Frattini sublattice `\Phi(L)` is the intersection - -" vs. "Returns
>> the Frattini subgroup of ``self``. The Frattini - -".
>>
>> 1) Should we include symbols in docstrings? I.e. add \otimes to
>> ordinal_product() of posets, as used in Enumerative combinatorics?
>
>
> IMHO, yes. They are nicely rendered in the html documentation, either in the
> notebook or in the reference manual pages.  The only trouble is of the
> course
> the ?-help in the console mode, but this seems a minor issue since

> we may assume that most users understand LaTeX.

This is a questionable assumption.  Numerical most users of Sage are
undergraduates, and most undergraduates don't know about LaTeX.

The Sage developer's guide says

**Readability balance:** in the interactive console, LaTeX formulas contained in
the documentation are represented by their LaTeX code (with
backslashes stripped). In this situation ``\\frac{a}{b}`` is less readable than ``a/b``
or ``a b^{-1}`` (some users may not even know LaTeX code). Make it pleasant for
everybody as much as you can manage.

--
John

[Travis Scrimshaw]

More on docstrings:

"The Frattini sublattice `\Phi(L)` is the intersection - -" vs. "Returns
the Frattini subgroup of ``self``. The Frattini - -".

1) Should we include symbols in docstrings? I.e. add \otimes to
ordinal_product() of posets, as used in Enumerative combinatorics?

IMHO, yes. They are nicely rendered in the html documentation, either in the
notebook or in the reference manual pages.  The only trouble is of the course
the ?-help in the console mode, but this seems a minor issue since we may
assume that most users understand LaTeX.

I try to avoid putting Latex in the first line so there will never be any confusion or having to parse latex. However, the ? doc also does some replacements of common latex like \leq for <=.

2) What about `self` in docstrings? I have avoided it, as was suggested to
me maybe a year ago. I write for example "Return True if the poset is
connected - -", i.e. "the poset" instead of "``self``".

There was a discussion about this some time ago:
https://groups.google.com/d/msg/sage-devel/58RUzV32vI0/rf4Mldr60JkJ
and the conclusion was that we should avoid to use ``self`` in the documentation.
Indeed, for a new user, not very familiar of Python, having ``self`` in the output
of the ?-help can be disturbing. 

That was not my impression at all from reading that discussion. The conclusion was to not put ``self`` as an *input* argument. Volker was advocating that we should not even refer to either ``self`` or "this object". If a new user does not understand ``self``, then the user will likely have problems using Sage (and likely reading the [English] documentation). In particular, see William's first post on this other thread: it implies we use it far more often than "this object" and it is better practice wrt to explicitness.

Best,
Travis

[Jean-Pierre Flori]

Hi all,

Slightly off-topic, but before deciding whether we use LaTeX or not, it would be nice to document how to use latex/tt font in the doc.

Each time I happen to write some doc I cannot remember what backquotes and double backquotes do and you have to look deep inside the rest/sphinx doc to get what (double?) backquotes do: king of tt font, and that the other one can be freely configure : therefore it has to be the latex one.
And I never found this info in the sage docs. Maybe things have changed recently or I was not good at searching.
I'm not even sure you have to use the same syntax in trac and in our docs.

A quick primer on this, using * for bold stuff and so on would be very nice to have even if you can rebuild the info yourself after googling and dwelling in sphinx doc.

Best,
JP

[Eric Gourgoulhon]

Le vendredi 25 septembre 2015 16:47:23 UTC+2, William a écrit :

> we may assume that most users understand LaTeX.

This is a questionable assumption.  Numerical most users of Sage are
undergraduates, and most undergraduates don't know about LaTeX.

Yes you are right!

The mission statement of Sage is also to be a viable alternative to
Maple, Mathematica, Matlab, and Magma, and those systems definitely
aspire to be undergraduate friendly.

I wonder if there are latex --> ascii art converters (?) -- maybe the
command line help could run text through that?

I am just realizing that, contrary to the standard Sage notebook, the LaTeX
of the command line help is not rendered in the SMC. Is there a way to
implement this ? Same question for the Jupyter notebook.

Best wishes,

Eric.

[William Stein]

I had not realized that I forgot to implement that. I've opened a ticket:

https://github.com/sagemathinc/smc/issues/131

[Jori Mäntysalo]

On Fri, 25 Sep 2015, William Stein wrote:

>>> 1) Should we include symbols in docstrings? I.e. add \otimes to
>>> ordinal_product() of posets, as used in Enumerative combinatorics?

>> IMHO, yes. They are nicely rendered in the html documentation, either
>> in the notebook or in the reference manual pages. The only trouble is
>> of the course the ?-help in the console mode, but this seems a minor
>> issue since we may assume that most users understand LaTeX.

> This is a questionable assumption. Numerical most users of Sage are
> undergraduates, and most undergraduates don't know about LaTeX.

True. On the other hand, how many undergraduates use Sage from command
line?

This is a real question. Personally I always start to play with notebook,
and then write a .sage if needed; I use command line only when developing
and even then usually to check something. (Strange - for other things I
use command line very much.)

...and hence I totally forget the command line usage. Maybe it is not
meaningful to add a symbol just for showing what symbol is usually used.

> The mission statement of Sage is also to be a viable alternative to
> Maple, Mathematica, Matlab, and Magma, and those systems definitely
> aspire to be undergraduate friendly.

True. And there has been few suggestions that would be good for that end.
Like hiding TESTS-parts with foldable html manual and so on. And having an
index of functions by topic, not by technical implementation with some
codes in categories/* and most elsewhere... (yeah yeah, was already
rejected.)

--
Jori Mäntysalo

[William Stein]

On Sun, Sep 27, 2015 at 11:39 PM, Jori Mäntysalo <Jori.Ma...@uta.fi> wrote:
> On Fri, 25 Sep 2015, William Stein wrote:
>
>>>> 1) Should we include symbols in docstrings? I.e. add \otimes to
>>>> ordinal_product() of posets, as used in Enumerative combinatorics?
>
>
>>> IMHO, yes. They are nicely rendered in the html documentation, either in
>>> the notebook or in the reference manual pages. The only trouble is of the
>>> course the ?-help in the console mode, but this seems a minor issue since we
>>> may assume that most users understand LaTeX.
>
>
>> This is a questionable assumption. Numerical most users of Sage are
>> undergraduates, and most undergraduates don't know about LaTeX.
>
>
> True. On the other hand, how many undergraduates use Sage from command line?
>
> This is a real question. Personally I always start to play with notebook,
> and then write a .sage if needed; I use command line only when developing
> and even then usually to check something. (Strange - for other things I use
> command line very much.)

I think it is *highly* unlikely that undergraduates use Sage (or
anything) from the command line. In my own surveys, most undergrads
never touch the command line.

>
> ...and hence I totally forget the command line usage. Maybe it is not
> meaningful to add a symbol just for showing what symbol is usually used.

You have a very good point.

>
>> The mission statement of Sage is also to be a viable alternative to Maple,
>> Mathematica, Matlab, and Magma, and those systems definitely aspire to be
>> undergraduate friendly.
>
>
> True. And there has been few suggestions that would be good for that end.
> Like hiding TESTS-parts with foldable html manual and so on. And having an
> index of functions by topic, not by technical implementation with some codes
> in categories/* and most elsewhere... (yeah yeah, was already rejected.)

Sounds like great ideas.

I can't believe TESTS is still not foldable!? Woah -- that was the
plan like 8 years ago and it's not done. Oops.

William


--
William (http://wstein.org)

[Jori Mäntysalo]

On Fri, 25 Sep 2015, Travis Scrimshaw wrote:

>>> 2) What about `self` in docstrings?

>> There was a discussion about this some time ago:
>> https://groups.google.com/d/msg/sage-devel/58RUzV32vI0/rf4Mldr60JkJ
>> and the conclusion was that we should avoid to use ``self`` in the
>> documentation.

> That was not my impression at all from reading that discussion. The
> conclusion was to not put ``self`` as an *input* argument. Volker was
> advocating that we should not even refer to either ``self`` or "this
> object". If a new user does not understand ``self``, then the user will
> likely have problems using Sage (and likely reading the [English]
> documentation). In particular, see William's first post on this other
> thread: it implies we use it far more often than "this object" and it is
> better practice wrt to explicitness.

True, there was no clear consensus on the thread. (Except that INPUT shall
not contain `self`.)

I like "the thing" instead of "``self``", but whatever is OK to me, as
long as it is unified.

--
Jori Mäntysalo

[Eric Gourgoulhon]

Le lundi 28 septembre 2015 08:46:12 UTC+2, Jori Mäntysalo a écrit :

On Fri, 25 Sep 2015, Travis Scrimshaw wrote:

>>> 2) What about `self` in docstrings?

>> There was a discussion about this some time ago:
>> https://groups.google.com/d/msg/sage-devel/58RUzV32vI0/rf4Mldr60JkJ
>> and the conclusion was that we should avoid to use ``self`` in the
>> documentation.

> That was not my impression at all from reading that discussion. The
> conclusion was to not put ``self`` as an *input* argument. Volker was
> advocating that we should not even refer to either ``self`` or "this
> object". If a new user does not understand ``self``, then the user will
> likely have problems using Sage (and likely reading the [English]
> documentation). In particular, see William's first post on this other
> thread: it implies we use it far more often than "this object" and it is
> better practice wrt to explicitness.

True, there was no clear consensus on the thread. (Except that INPUT shall
not contain `self`.)

Apologies for having misinterpreted the conclusion of this thread. I've read it again
and indeed there was no consensus, except for the INPUT section. Thanks Travis
for pointing this.

 

I like "the thing" instead of "``self``", but whatever is OK to me, as
long as it is unified.

A compromise would be to avoid ``self`` in the docstrings of public methods
(the only ones read by end-users) but use it in the docstrings of
private methods (to be read by developers).

For long docstrings, in order to avoid numerous occurrence of "this object"
or "this thing", one could write something like

... this object (denoted by ``self`` in what follows) ...

and use ``self`` everywhere in the remaining of the docstring, for it is clear
that ``self`` is totally unambiguous.

Eric.

[Jori Mäntysalo]

On Thu, 1 Oct 2015, Eric Gourgoulhon wrote:

>>>> 2) What about `self` in docstrings?

>>> There was a discussion about this some time ago
>>> https://groups.google.com/d/msg/sage-devel/58RUzV32vI0/rf4Mldr60JkJ

> A compromise would be to avoid ``self`` in the docstrings of public methods
> (the only ones read by end-users) but use it in the docstrings of
> private methods (to be read by developers).
>
> For long docstrings, in order to avoid numerous occurrence of "this object"
> or "this thing", one could write something like
>
> ... this object (denoted by ``self`` in what follows) ...

This is OK for me. But usually it seems better to say something like

def foo(self, x):
"""
Return foo value of x of the thing.

For a thing `A` and a real number `x` we define foo value to be
... where `y` is the number of elements in `A` such that `x` ...
"""


--
Jori Mäntysalo