Polys might makes more sense under "basics" with the current organization. However, even with "basics", I sometimes have a hard time realizing that I should look there. Maybe the name "basics" isn't very good.
I never really considered polys a top-level thing because despite its importance for the core, it's not something that most end-users should care about. Some very simple improvements I see that can be made are - Make sure that the pages in the left sidebar are always in alphabetical order. Right now the stuff under "basics" isn't. That way if you know what you are looking for it's easy to find. - Keep the section titles as short as possible. It's hard to peruse the polys sections in the left sidebar because they are so long. - Make sure each page has a top-level heading. I discovered that the way Furo creates sections for the left sidebar is it makes one section per top-level header. That means that a page like https://docs.sympy.org/dev/modules/codegen.html#code-printers-sympy-printing gets all of its headings in the left sidebar and nothing in the right sidebar. This can be fixed by adding a top-level heading like =============== Code Generation =============== to the top of the page. I made a similar change here https://github.com/sympy/sympy/pull/23488/commits/737b15afbb02370ba9ebb58f51e5bae17435cefc . - Clean up some of the redundant "index" pages. I think that pages like the one Oscar liked to ( https://docs.sympy.org/dev/reference/public/topics/index.html) are mostly useless now that we have the sidebars in the theme. Maybe others will disagree here. At the very least, if that page is going to exist, it should have some text instead of just being a table of contents. On Wed, Jun 8, 2022 at 4:01 PM Oscar Benjamin <oscar.j.benja...@gmail.com> wrote: > Hi all, > > I was looking at the SymPy docs earlier today and I found that it was > quite difficult to find the docs for the polys module. I'm interested > to know what people think about how the API docs are organised because > I see at least some problems but I'd like to know more from a user > perspective what people think about it. > > You can see the dev version of the docs here: > https://docs.sympy.org/dev/index.html > > That's how the docs are expected to look after the next release and it > does feel a lot nicer with the theme change compared to the 1.10 docs: > https://docs.sympy.org/latest/index.html > > The problem I have though is really to do with the API reference page: > https://docs.sympy.org/dev/reference/index.html#reference > > I remember spending some time with Aaron and Joannah coming up with > how to organise this but it seemed difficult at the time to come up > with a good "hierarchy" to break down the different modules in SymPy. > From memory we just came up with something and thought that we could > improve it later based on feedback or something but that structure > remained. > > The API reference page has a heading called "Topics". The text > underneath mentions "polynomials". When I click the "Topics" header I > get here: > https://docs.sympy.org/dev/reference/public/topics/index.html#topics > > It's quite hard to see polynomials there and I missed it the first few > times I looked at that page. SymPy's polynomials module is one of the > more well developed parts of SymPy and is extremely useful. It is also > a really core part of SymPy that is used all the time as part of any > simple operation as well as having extremely useful functions for end > users. Putting polys on the same level as "category theory" or > "cryptography" seems totally wrong to me given that those are both > modules that are completely unused internally and are probably not > used externally for anything significant. > > I think our goal at the time to break down the list of submodules into > a small number of categories for the API reference was a good idea but > I don't think we got the categories right. For example polys should be > at least on the same level as matrices right up there with a top link > in the main page. > > Does anyone have any idea what would be a better structure here? Which > topics should be listed right up top and which should be in > subheadings like "topics" and so on? > > For some sort of metric here's a quick count of the number of lines of > code in each submodule of SymPy. According to git ls-files there are > 843064 lines of code in total in SymPy. Here's the breakdown in terms > of submodules (showing that polys makes up 10% of the whole codebase!) > and how many lines of code they have: > I'm curious how you get this output from git ls-files. I don't see any flags to count line numbers or restrict to a directory level. > > 111849 sympy/integrals > I'm pretty sure this is all because of RUBI, which has several huge files with patterns. > 89184 sympy/polys > 67999 sympy/physics > 56055 sympy/core > 46909 sympy/printing > 43640 sympy/solvers > 40034 sympy/functions > 32076 sympy/matrices > 31561 sympy/utilities > 25289 sympy/combinatorics > 23812 sympy/parsing > 22257 sympy/stats > 18966 sympy/tensor > 18025 sympy/simplify > 15448 sympy/geometry > 11481 sympy/assumptions > 10979 sympy/series > 10662 sympy/ntheory > 10582 sympy/plotting > 10346 sympy/sets > 7061 sympy/concrete > 6865 sympy/logic > 6779 sympy/vector > 6181 sympy/codegen > 4731 sympy/categories > 4299 sympy/holonomic > 4121 sympy/testing > 3958 sympy/crypto > 3664 sympy/calculus > 3048 sympy/diffgeom > 2194 sympy/liealgebras > 1916 sympy/external > 1678 sympy/discrete > 1448 sympy/algebras > 1423 sympy/interactive > 1242 sympy/strategies > 1237 sympy/multipledispatch > 752 sympy/unify > 531 sympy/__init__.py > 478 sympy/benchmarks > 111 sympy/abc.py > 105 sympy/sandbox > 074 sympy/conftest.py > 021 sympy/this.py > 001 sympy/release.py > 001 sympy/galgebra.py > > Of course lines of code might not be a reasonable metric for what's > relevant to users. I think there is something wrong though if the > largest modules like integrals or polys don't even have a top-level > mention or are hard to navigate to. Another problem is the fact that > many of these headings don't make much sense e.g. all the limits code > is in the series module and I'm not sure that would be obvious to > anyone from outside. The above list gives similar lines of code the > logic module and the holonomic module but the logic module is used all > the time and I've never heard of anyone using holonomic... > > Ideally the reference API docs tree would make it easy to peruse the > overall features of SymPy as a library and give some impression of > what it does. The old list that just showed every submodule in > alphabetical order wasn't much use because it gave undue prominence to > things that have their own top-level submodule for no particular > reason. I don't think we've really succeeded in coming up with a good > organisation of the topics and features of SymPy here though. > > Does anyone have any thoughts about how to do this better? What topics > should be more prominent? Do the headings on the reference API page > even make sense? > I think we can easily move things around. None of the page URLs reference the categories, so the URLs won't break if we rename a category or move something to another category. The only URL that might break is the top-level index pages which I mentioned earlier would be better to either remove entirely or make more useful. I think it comes back to the discussion we had about making the reference documentation organized distinctly from the actual submodules, and having a separate docs page that exactly matches the submodules, and also inlcudes documentation for private functions. 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 sympy+unsubscr...@googlegroups.com. > To view this discussion on the web visit > https://groups.google.com/d/msgid/sympy/CAHVvXxQJkbPWrm3qhs6E9RU3OG7hoVMOx11H5q4RtO1Lx0ZVhQ%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%3D6%2BExzps%2BY5E_K8xwjRyBCu4dXfq7Quh7oR6EJUGtf0ydw%40mail.gmail.com.
