On Sat, Aug 10, 2019 at 9:57 AM Jason Moore <moorepa...@gmail.com> wrote: > > I one of the advocates of de-emphasizing complex math that requires latex in > the docsrings. When I'm programming my primary needs 1) are finding the > variable, function, or class that needs to be used and then 2) understanding > how to use that object. I am rarely concerned with the mathematical details, > as that is something I've likely sorted out before doing interactive > programming. For finding the function I need, I turn to Google or > searching/browsing the SymPy docs directly if I can't guess it. For > understanding how to use the function I rarely search the online > documentation and highly prefer using IPython's ? for showing the docstring > at the command line. I almost never use the command line or online SymPy > documentation for understanding a mathematical concept, Google's top hits on > that concept are typically where I garner that information. For the case of > uppergamma, the complex latex at the top of the docstring is not helpful when > trying to use the function, I'm very unlikely to try to read it. I rewrote > the uppergamma docstring here:
If you're arguing against having the mathematical definitions inside the functions, I strongly disagree with that. I use that all the time. Especially when something like integrate() returns a special function that I'm unfamiliar with. And just linking to Wikipedia isn't always enough, because sometimes functions have alternate definitions (for example, Fourier transformations have three different conventions). So it's good to have the definition right there in the docstring, so you know exactly what it is. > > https://github.com/sympy/sympy/pull/17378 > > to give an example of how you can put the information a programmer needs at > the top in plain text readable form and push the complex LaTeX and > mathematical details lower in the notes section. Both Python's help() and > IPython's ? results are shown in the PR. I don't feel strongly about the order. It seems natural to me that the definition should go at the top, and any other mathematical details in the notes section. But generally the best order to have stuff in a docstring is something I hope Lauren can help us work out and write out in a style guide. Aaron Meurer > > Jason > moorepants.info > +01 530-601-9791 > > > On Fri, Aug 9, 2019 at 2:33 PM Aaron Meurer <asmeu...@gmail.com> wrote: >> >> Another thing that will probably come up, related to the mathematical >> formatting, is to what degree formulas in docstrings should be >> formatted with LaTeX. Consider something like >> https://docs.sympy.org/latest/modules/functions/special.html#sympy.functions.special.gamma_functions.uppergamma. >> The mathematical definition of the function is given in LaTeX, which >> is really easy to read in the HTML rendered page. But in the plain >> text, the LaTeX is harder to parse >> https://github.com/sympy/sympy/blob/36c2e2abec058d0011102cda59d9848055de086c/sympy/functions/special/gamma_functions.py#L344. >> >> I'm personally of the opinion that we should use LaTeX for these >> cases, but others in the community have voiced alternate opinions in >> the past, specifically concerns that it is difficult to read in the >> plain text form. So it's worth being aware that this is an issue where >> we may not have yet reached consensus as a community. For now, the de >> facto standard, as you can see from the page I linked above, is to use >> LaTeX, although there are some places that do not. Here is the issue >> in the issue tracker with the discussion >> https://github.com/sympy/sympy/issues/14964. >> >> Aaron Meurer >> >> On Fri, Aug 9, 2019 at 1:51 PM Lauren Glattly <laurenglat...@gmail.com> >> wrote: >> > >> > Thanks for these thoughts so far Aaron and Matthew! It sounds like some of >> > the inconsistencies SymPy is dealing with are somewhat similar to >> > inconsistencies I've been addressing in Astropy's documentation. I'll >> > start compiling these suggestions into a doc so we can refine what my top >> > priorities will be for the project! >> > >> > On Fri, Aug 9, 2019 at 4:08 AM Matthew Brett <matthew.br...@gmail.com> >> > wrote: >> >> >> >> Hi, >> >> >> >> On Thu, Aug 8, 2019 at 6:23 PM Aaron Meurer <asmeu...@gmail.com> wrote: >> >> > >> >> > Hi Lauren. We are excited to have you working with us! >> >> > >> >> > On Thu, Aug 8, 2019 at 10:18 AM Lauren Glattly >> >> > <laurenglat...@gmail.com> wrote: >> >> > > >> >> > > Hi Sympyers! >> >> > > >> >> > > Thanks for the introduction Jason! I'm very excited to be >> >> > > participating in the inaugural Google Season of Docs with SymPy. I've >> >> > > been working as the technical copy editor for Astropy which has been >> >> > > a great experience all around, so I am delighted to be expanding my >> >> > > network within the open source community. I'd love to start hearing >> >> > > from users about what kinds of consistency issues I should be on the >> >> > > lookout for as I start to familiarize myself with SymPy's docstrings. >> >> > >> >> > Most things are listed on the issues that are linked on the ideas page >> >> > https://github.com/sympy/sympy/wiki/GSoD-2019-Ideas >> >> > >> >> > The SymPy docstrings, as you are probably already aware, have to major >> >> > forms. The docstring itself is written in RST (for example, >> >> > https://github.com/sympy/sympy/blob/ecd30247fd216432fb1b51020fa4c741ebe4c5af/sympy/solvers/solvers.py#L454), >> >> > and it is rendered as HTML on our docs website >> >> > (https://docs.sympy.org/latest/modules/solvers/solvers.html#sympy.solvers.solvers.solve). >> >> > Both forms should be readable, because people often get help for >> >> > things in interactive Python sessions, using help() or ? in Jupyter, >> >> > which gives the plain text form. The numpydoc Sphinx extension renders >> >> > special headers in the docstring in certain ways. For instance, a list >> >> > of functions under the "see also" header get rendered as a list of >> >> > links to those functions' documentation. >> >> > >> >> > The biggest issues with inconsistencies, I would say, come from the >> >> > HTML side. A large issue is that people don't always look at the >> >> > rendered HTML, and things that look just fine in plain text don't look >> >> > good in HTML. Some example issues >> >> > >> >> > - SymPy currently has Sphinx configured so that `text` between single >> >> > backticks renders as LaTeX math. In RST, ``text`` between double >> >> > backticks renders as code. However, most people are used to Markdown >> >> > from commenting on GitHub as well as other places, where single >> >> > backticks generate code. The result is that there is a lot of text in >> >> > docstrings that is rendered as LaTeX math when it shouldn't be. It >> >> > also doesn't help that there isn't a clear style guide to delineate >> >> > when the two forms should be used (it gets ambiguous because you can >> >> > represent mathematical expressions with SymPy in code). >> >> >> >> You might consider "math_dollar", originally by Ondrej, now in my >> >> "texext" package. It allows you to write math in the docstring like >> >> this: >> >> >> >> Here is some math $e^i + 2 \pi$ in a docstring >> >> >> >> The advantage of course is that the math is easier to read in the text >> >> form, and easier to type in, than the alternative: >> >> >> >> Here is some math :math:`e^i + 2 \pi` in a docstring >> >> >> >> which is pretty ugly on the eyes, >> >> >> >> Cheers, >> >> >> >> Matthew >> >> >> >> -- >> >> You received this message because you are subscribed to the Google Groups >> >> "sympy" group. >> >> To unsubscribe from this group and stop receiving emails from it, send an >> >> email to sympy+unsubscr...@googlegroups.com. >> >> To view this discussion on the web visit >> >> https://groups.google.com/d/msgid/sympy/CAH6Pt5pxNq6S7Af94rdN0v_VnBp42%2Bz8zweVeVEi3CTem7iXuA%40mail.gmail.com. >> > >> > -- >> > You received this message because you are subscribed to the Google Groups >> > "sympy" group. >> > To unsubscribe from this group and stop receiving emails from it, send an >> > email to sympy+unsubscr...@googlegroups.com. >> > To view this discussion on the web visit >> > https://groups.google.com/d/msgid/sympy/CANA%2BcPt8hL%3DdDw1cFCBcArAr3Ba_heHfKQHKqia6UQteGbEPNg%40mail.gmail.com. -- You received this message because you are subscribed to the Google Groups "sympy" group. To unsubscribe from this group and stop receiving emails from it, send an email to sympy+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/CAKgW%3D6%2Bjf9uxK4dJn3nhbQuJfssL7WpwCcu-PvCpVEqjxDvOhQ%40mail.gmail.com.
