Here's a first pass and cleaning up the top-level organization. I will look at cleaning up the API docs sections in a separate PR. https://github.com/sympy/sympy/pull/23669
Aaron Meurer On Sun, Jun 19, 2022 at 5:14 PM Aaron Meurer <[email protected]> wrote: > > > On Jun 19, 2022, at 5:50 AM, Oscar Benjamin <[email protected]> > wrote: > > > > On Sun, 19 Jun 2022 at 09:01, Aaron Meurer <[email protected]> wrote: > >> > >>> On Sat, Jun 18, 2022 at 3:49 PM Oscar Benjamin < > [email protected]> wrote: > >>> > >>> On Sat, 18 Jun 2022 at 13:45, Jeremy Monat <[email protected]> wrote: > >>>> > >>>> Aaron Meurer pointed out that we should move the solving main page > before the next release, so the page is in its final location when it gets > published to the "latest" (not dev) version of the documentation web site. > Given that, I'll make a simple pull request to reorganize the solving main > page from guides/solving.md to guides/solving/index.md. > >>>> > >>>> I included that reorganization in my draft pull request #23638 > Documentation guide: Solve an equation algebraically but the new sub-page > is still very much in development, so I'll split out the reorganization > into its own pull request. > >>> > >>> This reminds me that also I'm not really happy with the current > >>> organisation of the API docs: > >>> https://groups.google.com/g/sympy/c/L2zd54HDAxU > >>> > >>> If anyone wants to put some work into that then it would be good to > >>> get something in before the next release. > >> > >> > >> Isn't this something that's already a problem with 1.10? The only > difference in dev is the new theme, which makes organization issues more > evident. > > > > Yes, it's already a problem in 1.10. Ideally we would make it not be a > > problem in 1.11 though. > > > > Imagine being a new user or even an experienced user or contributor > > and you go to consult the docs for something starting from the main > > page: > > https://docs.sympy.org/dev/index.html > > > > From there clicking through the different headings and then clicking > > through from those pages still nothing really makes sense. The guides > > section is mostly about contributing to SymPy apart from one very long > > page about the old assumptions. The tutorials page makes sense but the > > most important part (installing sympy) is for some reason in the > > guides section rather than the tutorial section. Probably there should > > be a big fat "installing" link right on the main page of the docs > > (perhaps similar for "contributing"). The "explanation" section seems > > completely random when you go and look at what's in there. > > I can take a look at this this week, but I can't promise what can be done > by the release. The whole thing is rather bikesheddy, so it might be hard > to come to a good consensus. > > The main thing I would worry about is any change to the layout that would > break urls, as those would need redirects to keep them from breaking. The > api categories aren't part of the urls, but the top level categories are. > > I think the top level categories are actually fine, though. They just need > better explanations of what they are. The separation is based on Diataxis, > but that isn't clear from the text on the main page. It's true there aren't > many guides yet but that is going to change soon (we already have my work > on the custom functions guide and Jeremy's work on the solvers guide). > > > > > Then there's the API reference which is organised in a way that > > doesn't really reflect any particular organisation that makes sense to > > anyone I think. It doesn't really break down into the kinds of things > > that users might want to do. Probably most of what a beginner would > > want to do is in "basics" but once you click through there the > > important stuff like "solvers" is really not very prominent. > > > > Clearly a lot of work is still needed on the organisation here but the > > basic question I want to ask about here is for the API reference: what > > is a good way to group the different aspects of SymPy into > > approximately 5 different categories that actually makes sense to > > users and also reflects what SymPy is actually useful for? > > Is there a reason to not have more than 5 categories? With the new Furo > theme sidebar navigation it's easier to deal with top level nesting. > > Aaron Meurer > > > > > -- > > 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/CAHVvXxRSj0KK%2BCeurbPiLtSB06qeUOJbRq%2Be%3Do3wFeu40j9_JA%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 [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/CAKgW%3D6%2BLirjNGu7dFDPuLjscMO9hSviiUuEx-YwaFgmkb-mqZw%40mail.gmail.com.
