Google Season of Docs Participants Announced

[Jason Moore]

Sympyers,

We are happy to announce our first participation in Google's new "Season of Docs" with Lauren Glattly. Lauren's proposal was selected from 12 applications. She is a technical writer by trade and will be working on consistency and improvements to our docstrings. We are now starting the community bonding period. Please welcome Lauren and help her get familiar with the project as well as provide your thoughts on what needs to be improved with our documentation. She will be working with us for 3 months (similar to GSoC) starting September 2nd.

You can learn more about Lauren at her website: http://www.laurenglattly.com/

We'd also like to thank all applicants for their submissions.

Jason

moorepants.info
+01 530-601-9791

[Lauren Glattly]

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.

Looking forward to working together this fall!

Lauren

[Aaron Meurer]

Hi Lauren. We are excited to have you working with us!

On Thu, Aug 8, 2019 at 10:18 AM Lauren Glattly <lauren...@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).

I would actually like to change our Sphinx so that `text` formats as
code, and :math:`text` is required to get LaTeX math. However, this
will require going through every docstring in SymPy and fixing every
use of single backquotes. I think we can write a script to do this
automatically, but that doesn't solve the problem that a large portion
of them are incorrectly rendered. See
https://github.com/sympy/sympy/issues/13519

- A related problem is that sometimes the LaTeX math is not formatted
correctly. As I noted, not everyone takes the time to look at the
rendered Sphinx for their documentation (if you have any thoughts on
how to improve this let us know). For example, sometimes people will
write "a*b" in a LaTeX formula. The * is necessary in code, but in
LaTeX, multiplication should be written as just "ab".

- Some formatting, such as ``code``, is not always used when it should
be. Anything that references a variable name should be formatted as
``code``, for instance.

- Every docstring should have the predefined headers I mentioned above
(see also, examples, etc.), if possible. I don't know if it should
necessarily be your responsibility to write them for the docstrings
that are missing them, since that requires technical knowledge of the
specific functions. However, it will be good to have 1) an official
guide on what should be there, and 2) a way to see which docstrings
are missing what.

- I think a big thing that is missing is formatting of argument
parameters. For instance, in the solve() docstring I linked to above,
all the argument parameters are documented, but the formatting is
haphazard. Other functions are missing them entirely. We should have a
consistent formatting style for these, perhaps using the numpydoc
format that already exists.

Aaron Meurer

>
> Looking forward to working together this fall!
>
> Lauren
>
> On Thu, Aug 8, 2019 at 10:53 AM Jason Moore <moore...@gmail.com> wrote:
>>
>> Sympyers,
>>
>> We are happy to announce our first participation in Google's new "Season of Docs" with Lauren Glattly. Lauren's proposal was selected from 12 applications. She is a technical writer by trade and will be working on consistency and improvements to our docstrings. We are now starting the community bonding period. Please welcome Lauren and help her get familiar with the project as well as provide your thoughts on what needs to be improved with our documentation. She will be working with us for 3 months (similar to GSoC) starting September 2nd.
>>
>> You can learn more about Lauren at her website: http://www.laurenglattly.com/
>>
>> We'd also like to thank all applicants for their submissions.
>>
>> Jason
>> moorepants.info
>> +01 530-601-9791
>

> --
> 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+un...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/CANA%2BcPuSidmXzVWRveRAfpc4i3BvumOZxLw7OA1JXXwL3DRA%3Dw%40mail.gmail.com.

[Matthew Brett]

Hi,

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

[Lauren Glattly]

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!

--
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+un...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/CAH6Pt5pxNq6S7Af94rdN0v_VnBp42%2Bz8zweVeVEi3CTem7iXuA%40mail.gmail.com.

[Aaron Meurer]

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

> To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/CANA%2BcPt8hL%3DdDw1cFCBcArAr3Ba_heHfKQHKqia6UQteGbEPNg%40mail.gmail.com.

[Alan Bromborsky]

I think LaTeX is essential.  Has anyone though of the relationship of
docs to Jupyter notebook/lab?  Do you want to be able to launch a
notebook from the doc?

[Jason Moore]

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:

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.

Jason

moorepants.info
+01 530-601-9791

[Aaron Meurer]

On Sat, Aug 10, 2019 at 9:57 AM Jason Moore <moore...@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 Moore]

> If you're arguing against having the mathematical definitions inside the functions

No where have I argued for that.

Jason

moorepants.info
+01 530-601-9791

[Aaron Meurer]

On Mon, Aug 12, 2019 at 8:43 AM Jason Moore <moore...@gmail.com> wrote:
>
> > If you're arguing against having the mathematical definitions inside the functions
>
> No where have I argued for that.

If this isn't what you are suggesting then that's great. It sounded
like you were, but I may have misread what you wrote. Note that the
"complex mathematical expression" at the top of the uppergamma
docstring is the definition of the uppergamma function.

> To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/CAP7f1AhbdxaTFCkcPo2uF-Vs0WVeTbUoOAQ7-Xcpq20-ZcR4tg%40mail.gmail.com.

[Jason Moore]

Yes and I moved it to the notes section in the example. I de-emphasized the "complex mathematical expression" written in latex because It is unhelpful in plaintext.

Jason

moorepants.info
+01 530-601-9791

To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/CAKgW%3D6LR%2B26R7RRpLtHc_DhbAObsm37zUS9nL283kV63eG54TA%40mail.gmail.com.

[Ondřej Čertík]

On Mon, Aug 12, 2019, at 9:03 AM, Jason Moore wrote:
> Yes and I moved it to the notes section in the example. I de-emphasized
> the "complex mathematical expression" written in latex because It is
> unhelpful in plaintext.

Here is another idea that I had recently, which might be a nice solution for this:

https://github.com/sympy/sympy/issues/14964#issuecomment-520622196

There are a lot of details that we would have to figure out to make that work, but I like the idea quite a bit so far.

Ondrej

[Jason Moore]

The Fungrim form is readable in plaintext, which is a good thing. It is also easier to read a sympy integral than the latex too.

Jason

moorepants.info
+01 530-601-9791

--
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+un...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/a5176c9d-42f2-4e84-88ee-400a2f3b4613%40www.fastmail.com.

[Aaron Meurer]

A possible middle ground would be to print the definition as a SymPy
expression. The docstrings in the ODE module use the ODE module to
pretty print the general solution
https://docs.sympy.org/latest/modules/solvers/ode.html (unfortunately,
using the ASCII pretty printer, we could potentially use Unicode if we
fix https://github.com/sympy/sympy/issues/15700.

It doesn't apply to every function. Some formulas aren't expressible
in SymPy. I think a good middle ground would be to show the LaTeX, so
that it looks nice in the HTML, but also pretty print the formula in a
doctest so that it is readable in plain text (and also you get the
SymPy code for the definition formula). The only downside is that the
information becomes duplicated.

Another idea, I don't know how hard it would be, or how confusing the
output would be to people reading the page, would be to have a special
pretty print function that shows the pprint() output in the docstring
itself, but the Sphinx build would replace that with a LaTeX
representation.

Aaron Meurer

> To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/CAP7f1AgJG6-S8xfGPVoXmgg1PDq6eMikPYd59LP8%3Dx5c3mQ9fg%40mail.gmail.com.

[Ondřej Čertík]

On Mon, Aug 12, 2019, at 7:47 PM, Aaron Meurer wrote:
> A possible middle ground would be to print the definition as a SymPy
> expression. The docstrings in the ODE module use the ODE module to
> pretty print the general solution
> https://docs.sympy.org/latest/modules/solvers/ode.html (unfortunately,
> using the ASCII pretty printer, we could potentially use Unicode if we
> fix https://github.com/sympy/sympy/issues/15700.
>
> It doesn't apply to every function. Some formulas aren't expressible
> in SymPy. I think a good middle ground would be to show the LaTeX, so
> that it looks nice in the HTML, but also pretty print the formula in a
> doctest so that it is readable in plain text (and also you get the
> SymPy code for the definition formula). The only downside is that the
> information becomes duplicated.
>
> Another idea, I don't know how hard it would be, or how confusing the
> output would be to people reading the page, would be to have a special
> pretty print function that shows the pprint() output in the docstring
> itself, but the Sphinx build would replace that with a LaTeX
> representation.

We can port all missing features from Fungrim into SymPy, so that we can use SymPy itself to represent any math. There are a few things that can't be represented by SymPy naturally:

* such as "x+x".
* order of terms "x*y" vs "y*x", the same with "x+y" vs "y+x"

That is a fundamental design choice, needed for performance (even more so in SymEngine). Besides those, I don't know if there is some other obstacle to represent all the things from Fulgrim. When looking at the formulas that we need to represent, I don't think we ever need things like "x+x", but it would be useful to preserve the order of terms.

I don't know if there are other semantic differences between SymPy and Fungrim. Fredrik, do you know if there are other issues?

Ondrej

[Aaron Meurer]

Not all function definitions can be represented in SymPy. For instance
the Meijer G-function is defined by a path integral
(https://docs.sympy.org/latest/modules/functions/special.html#sympy.functions.special.hyper.meijerg),
and there's no way to make an Integral object in SymPy that is over a
path L. I don't know if the G-function is in fungrim. Fungrim seems to
be lacking a search functionality.

At any rate, this all seems out of scope for Lauren's project. I think
we should decide on something that we can do now for our docstring
standard. If we later decide that something like fungrim can replace
it, and we have the tooling written, we can change the standard.

Aaron Meurer

>
> Ondrej
>
> --
> 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+un...@googlegroups.com.

> To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/ae7bd8c1-b83a-4465-ad9a-54fdb5fc365d%40www.fastmail.com.

[Fredrik Johansson]

Apart from specific objects and functions that don't have definitions yet, nothing major as far as I know. There are probably differences in special values and the like; for example, log(0) is zoo in SymPy but it is (tentatively) -Infinity in Fungrim.

Here are some concrete limitations of the Fungrim formula language for writing semantic math right now:

* No formalization of variable-length tuples, variable-size matrices etc

* No formalization of functions (as mathematical objects, as opposed to just their defining expressions) and function spaces

* No formalization of formal variables (e.g. x as a formal generator of R[x], as opposed to a variable x representing an unknown value)

* No formalization of abstract algebraic structures

* The constructions for defining bound variables are not yet fully defined / consistent / unambiguous, making fully automatic semantic parsing problematic

Not all function definitions can be represented in SymPy. For instance
the Meijer G-function is defined by a path integral
(https://docs.sympy.org/latest/modules/functions/special.html#sympy.functions.special.hyper.meijerg),
and there's no way to make an Integral object in SymPy that is over a
path L. I don't know if the G-function is in fungrim. Fungrim seems to
be lacking a search functionality.

You can search the git repository, and http://fungrim.org/definitions.html currently has a list of symbols (though not every implemented symbol has been defined there yet).

Indeed, the Meijer G-function does not have a symbol yet. Paths and integrals over paths are also on the todo list!

At any rate, this all seems out of scope for Lauren's project. I think
we should decide on something that we can do now for our docstring
standard. If we later decide that something like fungrim can replace
it, and we have the tooling written, we can change the standard.

+1

However, there is some potential for collaboration already, related to this issue. One of the (many) reasons for creating Fungrim was that I find it cumbersome to put a lot of math in the documentation for mpmath and Arb; putting in links to Fungrim is an alternative. Here is an example: I recently put the Coulomb wave functions in Arb, and on

http://arblib.org/acb_hypgeom.html#coulomb-wave-functions

I just link to the page in Fungrim instead of giving all the formulas in the Arb documentation. In the source code

https://github.com/fredrik-johansson/arb/blob/master/acb_hypgeom/coulomb.c

https://github.com/fredrik-johansson/arb/blob/master/acb_hypgeom/coulomb_jet.c

I put in comments referencing the formula in Fungrim that is used in each case.

What I would like to do is to replace more of the existing formula-heavy documentation in mpmath and Arb with Fungrim links, as soon the content exists in Fungrim. Perhaps this would make sense for the SymPy documentation too.

Fredrik

[Jason Moore]

Here is another example taken from physics.vector.point. There is a method that calculates an acceleration (https://github.com/sympy/sympy/blob/master/sympy/physics/vector/point.py#L57). The docstring is currently:

        """Sets the acceleration of this point with the 1-point theory.

        The 1-point theory for point acceleration looks like this:

        ^N a^P = ^B a^P + ^N a^O + ^N alpha^B x r^OP + ^N omega^B x (^N omega^B
        x r^OP) + 2 ^N omega^B x ^B v^P

        where O is a point fixed in B, P is a point moving in B, and B is
        rotating in frame N.

        Parameters
        ==========

        otherpoint : Point
            The first point of the 1-point theory (O)
        outframe : ReferenceFrame
            The frame we want this point's acceleration defined in (N)
        fixedframe : ReferenceFrame
            The intermediate frame in this calculation (B)

        Examples
        ========

        >>> from sympy.physics.vector import Point, ReferenceFrame
        >>> from sympy.physics.vector import Vector, dynamicsymbols
        >>> q = dynamicsymbols('q')
        >>> q2 = dynamicsymbols('q2')
        >>> qd = dynamicsymbols('q', 1)
        >>> q2d = dynamicsymbols('q2', 1)
        >>> N = ReferenceFrame('N')
        >>> B = ReferenceFrame('B')
        >>> B.set_ang_vel(N, 5 * B.y)
        >>> O = Point('O')
        >>> P = O.locatenew('P', q * B.x)
        >>> P.set_vel(B, qd * B.x + q2d * B.y)
        >>> O.set_vel(N, 0)
        >>> P.a1pt_theory(O, N, B)
        (-25*q + q'')*B.x + q2''*B.y - 10*q'*B.z

        """

The method executes the mathematical expression shown in a pseudo math language. Here is what the correct latex would look like if we used that:

        .. math::

           ^N{\mathbf{a}}^P = ^B{\mathbf{a}}^P + ^N{\mathbf{a}}^O +
           ^N{\boldsymbol{\alpha}}^B \times \mathbf{r}^{O/P} +
           ^N{\boldsymbol{\omega}}^B \times (^N{\boldsymbol{\omega}}^B \times
           \mathbf{r}^{O/P}) + 2 ^N{\boldsymbol{\omega}}^B \times
           ^B{\mathbf{v}}^P

I don't see how that can be helpful at all to someone reading from plain text. In fact, I don't think the end user needs to know the mathematical equation at all to successfully understand and use the method. If the Parameters, Returns, and Examples sections are done well, that is all that is needed.

The math could alternatively be shown like this for some potential simplification for readability:

        NaP = BaP + NaO + cross(NαB, rOP) + cross(NωB, cross(NωB, rOP)) + 2 cross(NωB, BvP)

or

        NaP = BaP + NaO + NαB x rOP + NωB x (NωB x rOP) + 2 NωB x BvP

The primary issue I am attempting to express is that it is not very natural to read LaTeX (for a few maybe, but I doubt of most). I've been reading/wrting LaTex for 20 years now and it still very hard to read. It just wasn't designed to be readable. I thus find it unhelpful to have LaTeX at the front and center of a docstring. My use of docstrings is more-or-less simply to figure out how to properly call a method. I think that the numpydoc format has that as a design principal: show the user the call signature, Parameters, Returns, and Examples as the first thing, in that order. The more that clutters those or moves them deeper into the docstring detracts from that usefulness.

An ideal solution could be that the docstrings could be designed such that the rendered math appears in the online docs and doesn't (or a simplified version) appears at the command line. I don't know what the technical solution to make that happen would be.

Jason

moorepants.info
+01 530-601-9791

[Ondřej Čertík]

So for SymPy documentation, I am now thinking we should just use SymPy to represent all the equations (and add all missing functionality that's needed to do that), I think that can be more readable than LaTeX (what do you think Jason?), and we can still write tooling to convert it to nice equations online.

A few suggestions:

* You should enable https on the website and use https in the source code.
* how do you generate the text math, e.g., the second line in:

/* http://fungrim.org/entry/07a654/ */
/* F''/2 = q F, q = (2eta/z + l(l+1)/z^2 - 1)/2 */

the website itself might be able to give such text in many cases.

Ondrej

[Aaron Meurer]

We can write a Sphinx extension that lets you write

.. sympy::
Eq(uppergamma(s, x), Integral(t**(s - 1)*exp(-t), (t, x, oo)))

and Sphinx will pass the string through latex(sympify(...)). That way
we get the best of both worlds. The downside is that you are much more
limited in what you can represent. For instance, the current LaTeX
uses := to show that it is a definition, and that wouldn't be there in
this.

I do think that having the plain text docstrings human-readable is
important. But I also think that the majority of users read the
documentation on the website, so we should optimize for that. I don't
know that for sure, so maybe there is some way we could measure that.

I also want to reiterate that all of these suggestions require writing
new code to work. So unless someone implements them in the next couple
of weeks, I think for Lauren's project we should stick with the
current de facto standard of using ..math:: Maybe our docstring
standard should simply state that we haven't yet reached a consensus
about this as a community, so you should match the style of whatever
submodule your docstring is a part of.

Aaron Meurer

> --
> 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+un...@googlegroups.com.

> To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/535fb8c0-f188-44ea-a4fa-60d683b14a45%40www.fastmail.com.

[Jason Moore]

> I don't know that for sure, so maybe there is some way we could measure that.

This is something Lauren could do, a proper survey to solicit feedback on docstrings/documentation from users would really help. Right now we are just getting info from a few vocal speakers.

> Maybe our docstring standard should simply state that we haven't yet reached a consensus about this as a community,

If conversations about style of code/documentation of the past are any indication I don't think consensus will ever be reached (at least not in the way our large group arrives at consensus). I personally don't think we need consensus. I'm fine with letting Lauren take in the info she gets and produce a what she thinks is best. Projects like black arose because in some sense it doesn't matter what the details of the standard are, but simply that there is one. For example, if we have a LaTeX heavy docstring with consistency across all docstrings, I think that is better than having lack of consistency and different styles in each module.

Jason

moorepants.info
+01 530-601-9791

To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/CAKgW%3D6K%3DRhBeG1Yx2baep2eURokL7hA5CAn%2BJX5gJ1hnL7XqLQ%40mail.gmail.com.

[Aaron Meurer]

On Tue, Aug 13, 2019 at 10:49 AM Jason Moore <moore...@gmail.com> wrote:
>
> > I don't know that for sure, so maybe there is some way we could measure that.
>
> This is something Lauren could do, a proper survey to solicit feedback on docstrings/documentation from users would really help. Right now we are just getting info from a few vocal speakers.
>
> > Maybe our docstring standard should simply state that we haven't yet reached a consensus about this as a community,
>
> If conversations about style of code/documentation of the past are any indication I don't think consensus will ever be reached (at least not in the way our large group arrives at consensus). I personally don't think we need consensus. I'm fine with letting Lauren take in the info she gets and produce a what she thinks is best. Projects like black arose because in some sense it doesn't matter what the details of the standard are, but simply that there is one. For example, if we have a LaTeX heavy docstring with consistency across all docstrings, I think that is better than having lack of consistency and different styles in each module.

IMO intra-module consistency is more important than inter-module
consistency. The physics docstring example you showed is a very
different thing than a docstring for a special function definition. It
is a function that takes in certain arguments that have some meaning,
and returns something that also has some meaning. The types of those
arguments is important. For a special function, the arguments are just
expressions. Maybe in some cases they have mathematical type
restrictions (like only integers). There isn't really a return type;
it just returns the function object, which you then use in some larger
expression. Or for instance the ODE docstrings I mentioned all have a
convention to show the general solution. The convention to even have a
"LaTeX function definition" doesn't even make sense for many
docstrings. For instance, solve() and simplify() won't have this.

So the flavor is different, but I don't know to what degree this
should dictate a distinct style in the docstring. Probably there
should be a global style that applies to everything, and also certain
modules or certain types of functions will have sub-styles.

It's also worth pointing out that the examples I've given are all
instances where I think the documentation is already pretty good. I
wanted to show them as examples of what the documentation style could
look like. There are other modules in SymPy that are in need of
improvement. For example, the core is poorly documented, and the
docstrings that exist are missing a lot of the basic sections.

Aaron Meurer

> To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/CAP7f1Aiu3TfkF9m0AjR_W-u781J-RXeR62wQqm%2Bxcy2-HOM34g%40mail.gmail.com.

[Ondřej Čertík]

On Tue, Aug 13, 2019, at 10:49 AM, Jason Moore wrote:
> > I don't know that for sure, so maybe there is some way we could measure that.
>
> This is something Lauren could do, a proper survey to solicit feedback
> on docstrings/documentation from users would really help. Right now we
> are just getting info from a few vocal speakers.
>
> > Maybe our docstring standard should simply state that we haven't yet reached a consensus about this as a community,
>
> If conversations about style of code/documentation of the past are any
> indication I don't think consensus will ever be reached (at least not
> in the way our large group arrives at consensus). I personally don't
> think we need consensus. I'm fine with letting Lauren take in the info
> she gets and produce a what she thinks is best. Projects like black

> <https://black.readthedocs.io/> arose because in some sense it doesn't

> matter what the details of the standard are, but simply that there is
> one. For example, if we have a LaTeX heavy docstring with consistency
> across all docstrings, I think that is better than having lack of
> consistency and different styles in each module.

Yes, but I think it's a good occasion now to discuss and figure out a good solution. I am willing to write code for this, I think this is very important. If we can't figure this out in the next few weeks, then I agree, we will probably stick with LaTeX.

I like Aaron's suggestion:

.. sympy::
Eq(uppergamma(s, x), Integral(t**(s - 1)*exp(-t), (t, x, oo)))

And to fix the := issue, why not to add this semantics to SymPy, as follows:

.. sympy::
Def(uppergamma(s, x), Integral(t**(s - 1)*exp(-t), (t, x, oo)))

And SymPy will have the capability to convert the Def to Eq if requested, or anything else we deem appropriate (such as conversion to and from Fungrim).

Now take this example from our docs:

.. math::
\Gamma(x) := \int^{\infty}_{0} t^{x-1} e^{-t} \mathrm{d}t.

And the corresponding new way:

.. sympy::
Def(Gamma(x), Integral(t**(x-1)*exp(-t), (t, 0, oo)))

which is even 5 characters shorter. And our Sphinx extension can still convert it to the original LaTeX, it knows all the information.

I like this approach a lot.

Ondrej

[Jason Moore]

> I like this approach a lot.

I agree. It is a nice idea.

Jason

moorepants.info
+01 530-601-9791

--
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+un...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/49303907-5a06-4e3a-a1f3-17ac074f5475%40www.fastmail.com.

[Jason Moore]

I was thinking more about Aaron's mention of measuring the documentation use and started wondering how to get more and better insight into what is good and bad about our documentation. One issue that this conversation suffers from is that Aaron probably knows more about SymPy that almost anyone. Ondrej created it in 2006 and I've had 10 years experience with it too. I think it would be much more valuable to hear from new developers, non-developer users, and people that don't even know about SymPy. The old guns certainly have informed and useful insight to give but we simply don't use SymPy in the same way that these others do. They will likely give us insight that we really need to make the documentation useful and accessible.

With that in mind, a survey could be designed and sent out to our GSoC students form the last few years and we could post it to twitter and mailing lists (ours and others) to get some of the SymPy user base.

For non-sympy users, I can imagine that it would be extremely useful to watch someone new to SymPy try to use the documentation (like we might see in a live tutorial). You could give someone a little task like "find the solution to these linear equations" and see what they do. Or just ask them to take a look at the documentation website and give some feedback. You could also ask people to compare our documentation to another similar software package. Maybe you could ask someone to write a docstring for a function or class after explaining what it does verbally and see how they'd write it and ask them why they wrote it in that way. Lot's of ideas here, but they take concerted time.

Doing things like this could give us some nice data to support or not support various solutions.

Jason

moorepants.info
+01 530-601-9791

[Lauren Glattly]

I agree with Jason that a proper survey on how the SymPy documentation is used and by who could be helpful. One of the biggest conversations of Google Season of Docs (and something I'm seeing with other open source software projects) is "who is the audience of our documentation" and "how can it be made more useful to different levels of users."

It sounds like a solution to this LaTeX issue is important, and so maybe Ondrej's approach of coding a permanent solution is the right one, but if that can't happen in time for my work period with SymPy it could also be helpful to know how many SymPy users need to see things rendered nicely on the SymPy site, versus how many are accessing the plain text in a Python session or Jupyter and find it hard to read.

A survey could also help with the issue Aaron raised about consistency in a global sense or sub-style sense. This is also something I've run into before when creating style guides -- how guidelines that work well in one section of documentation may not make sense in another. There is no straightforward solution to this, just as in writing, guidelines are only ever guidelines, not hard and fast rules, and there will always be exceptions. A survey of the community to find out what parts of the documentation/docstring groups they are using/seeing together might help us determine if the formatting/style guide should be global across all docstrings or allow for sub-styles for different functions.

I will say that in some cases it almost doesn't matter what you choose, as long as you make it consistent across the documentation, as that is a key to raising the professionalism of documentation as a whole, but in this case it does sound like the choice between LaTeX or not is very important, which is why a survey might help.

Either way, this a great conversation to be having now!

To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/CAP7f1AjLRbo-NfbOrdnJUPfA8jctNi1f%3DV5irdMUvond6exnxQ%40mail.gmail.com.

[Jason Moore]

Lauren,

Great summary! Looking forward to what you can do with the info.

Jason

moorepants.info
+01 530-601-9791

To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/CANA%2BcPssDw%2Bo2Yk9E0F9yrx0ccF7S%3D0M7rRXZcDjOZgftOAb0Q%40mail.gmail.com.