On Mon, Nov 29, 2021 at 10:49 AM Jeremy Monat <[email protected]> wrote: > > David and Oscar, > > Glad there is agreement on the need for improved documentation! And that > there's a Google Summer of Documentation to go along with the one of Code. > > >There should be a guide somewhere that explains how to "solve equations". > Definitely--web searches for things such as "SymPy solve inequalities" return > the Inequality Solvers page, and there's nothing telling the visitor that > they should probably be using a high-level solver such as solve() or > solveset(). > > There also needs to be a page on how to programmatically parse results of > e.g. solve()--there's nothing on the site that I could find. For example, to > answer my StackOveflow question about parsing results, smichr put together > three concepts that I could not glean from the documentation, certainly not > all in one place: > > Solved inequalities can be parsed using .atoms() > .atoms() can be filtered using Relational > .canonical puts the atoms in order so the symbol is on the left > > I'd be happy to communicate with Joannah Nanjekye and Aaron Meurer about what > documentation is needed, how I can help with existing efforts, etc. Because > I'm new here, could you give me their contact information?
There's no need to contact me separately. It's best to do these discussions on the list. As Oscar mentioned, my work will mostly focus on writing new documentation guides. If you have any suggestions on the sorts of new documentation you'd like to see written, please let me know. Of course, just because I will be writing documentation doesn't mean you can't either. There is plenty of work to do. As a new user, you may have a better sense of what is lacking in the documentation than I do. Another piece of work that we need help with is updating the existing API documentation (docstrings) to conform to our style guide. https://docs.sympy.org/latest/documentation-style-guide.html. Some of the previous season of docs projects worked on this (see https://github.com/sympy/sympy/wiki/GSoD-2019-Report-Lauren-Glattly:-SymPy-Documentation-Style-Guide and https://github.com/sympy/sympy/wiki/GSoD-2020-Report-Soumi-Bardhan:-Consistency-across-docstrings---SymPy-Documentation), but the work is incomplete. As for Joannah, her project has just come to a conclusion. See https://github.com/sympy/sympy/wiki/GSoD-2021-Report-Joannah-Nanjekye:-Reorganizing-the-SymPy-Documentation. If you're interested in improving that work, see the "future work" section on that page. That work mostly involves doing technical work with Sphinx, so I would only recommend it if you have some familiarity with Sphinx already. Aaron Meurer > > Thanks, > Jeremy > On Sunday, November 28, 2021 at 3:37:02 PM UTC-5 Oscar wrote: >> >> On Sun, 28 Nov 2021 at 11:09, Jeremy Monat <[email protected]> wrote: >> > >> > Hello, I'm Jeremy Monat. My primary interest in helping with SymPy >> > development is making it easier for new users to use SymPy by improving >> > the documentation. It is plenty powerful for the application I needed; >> > learning how to use SymPy was the challenge for me. >> >> Hello and welcome Jeremy. Contributions to improving the documentation >> are absolutely welcome. There are a few things already happening in >> relation to this. >> >> We've just had a GSOD (Google Summer of Docs) project working on >> reorganising the documentation from a high-level. This was work by >> Joannah Nanjekye looking at different aspects of how to organise >> things. The most immediately noticeable change is the new front page >> which you can see in the dev docs for the next release: >> https://docs.sympy.org/latest/index.html >> https://docs.sympy.org/dev/index.html >> >> There is plenty more to do in terms of organisation. I'd like to break >> down the long API doc pages into smaller more organised pages more >> like this: >> https://numpy.org/doc/stable/reference/routines.fft.html >> There was a PR to do that somewhere but it seems to have stalled. >> >> Another thing happening right now is that Aaron Meurer is being funded >> by CZI to spend time writing new docs with a particular focus on >> guides for general usage rather than basic API docs. I bet Aaron would >> be grateful or any insights you have on what is really needed. >> >> Absolutely more is needed in improving the docs though. A good example >> is that you said your interest area was solvers. There should be a >> guide somewhere that explains how to "solve equations". There are so >> many different options for doing this in SymPy and I don't think many >> users understand what the pros and cons are or when each is >> applicable. Instead of a good guide explaining these we have things >> like this: >> https://docs.sympy.org/latest/modules/solvers/solveset.html#what-will-you-do-with-the-old-solve >> That page implies that solveset will replace solve and that solve >> should not be used any more (not at all true!). That kind of thing >> leads to a lot of confusion for people learning to use SymPy because >> it makes them think that they should use solveset instead of solve but >> solveset does not even begin to replace solve because it doesn't >> handle multivariate equations. >> >> -- >> Oscar > > -- > 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 [email protected]. > To view this discussion on the web visit > https://groups.google.com/d/msgid/sympy/11e75753-91be-4d3e-b18a-d744784b0badn%40googlegroups.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 [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/CAKgW%3D6%2B_uGxrMwbBv-o3_Lw8VhM9sZ81A_W-Z_cr5UZwZ6VqrQ%40mail.gmail.com.
