Aaron, Thanks for the information. While my exploration of SymPy is largely limited to solvers, here are the documentation improvements I think would be helpful:
1. Improve the tutorial solvers page <https://docs.sympy.org/latest/tutorial/solvers.html>'s order by first explaining how to solve equations and inequalities, particularly explaining the strengths of different solvers, when to use each, and giving examples of each (as suggested by Oscar) 1. Add an example to solveset() <https://docs.sympy.org/latest/modules/solvers/solveset.html> on how to solve a set of equations or inequalities in a single variable (if it does--the documentation is ambiguous on whether this is even possible) 2. Add an example to solve() <https://docs.sympy.org/latest/modules/solvers/solvers.html> on how to solve a set of equations or inequalities, in a single variable, then in multiple variables (if possible) 2. Add a guide on how to programmatically parse solved equations and inequalities <https://stackoverflow.com/questions/67153048/reliable-way-to-extract-values-from-parse-sympy-result> (atoms, canonical, etc.) 3. Add a guide on how to programmatically parse expressions (args <https://docs.sympy.org/latest/modules/core.html?highlight=args#sympy.core.basic.Basic.args>, other?) 4. At the top of each of the low-level solvers pages, put a note that you probably want to use a high-level solver instead--I reached the inequalities solvers page <https://docs.sympy.org/latest/modules/solvers/inequalities.html> via a web search, and thought I had to use it instead of solve 5. Use simpler math for examples, or at least the first example for a function. For example, that page on solving inequalities <https://docs.sympy.org/latest/modules/solvers/inequalities.html> has as its first example the following. I didn't know what the Poly function was (plus I couldn't find documentation for it), so I couldn't understand the solver. solve_rational_inequalities([[ ((Poly(-x + 1), Poly(1, x)), '>='), ((Poly(-x + 1), Poly(1, x)), '<=')]]) {1} The overall theme of 1-3 is "here's how to do things using easy-to-understand math" so maybe they'd be best in the tutorial rather than as reference pages. Best, Jeremy On Monday, November 29, 2021 at 1:59:30 PM UTC-5 asme...@gmail.com wrote: > On Mon, Nov 29, 2021 at 10:49 AM Jeremy Monat <jem...@gmail.com> 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 <jem...@gmail.com> 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 sympy+un...@googlegroups.com. > > 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 sympy+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/6a73a50e-9b49-44ba-b1c1-f5bd731fb3c4n%40googlegroups.com.
