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?
On 8/9/19 5:33 PM, Aaron Meurer 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/34bc7e93-8b63-530b-22dd-3f155726e090%40gmail.com.
