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. -- 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 http://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
