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