On Sat, Feb 26, 2022 at 1:11 AM Jason Moore <moorepa...@gmail.com> wrote: > > Thanks for doing this! I read through all the comments. > > Couple of points: > > - With 22 respondents and large standard deviation, the numbers don't really > mean anything. Basically all themes are rated the same. > - The written comments are most useful and I get the impression that almost > any of the themes could work, but each requires some tweaking to fit for > SymPy. > > I would recommend choosing based on which theme has the most configuration > options and energy behind it because we want to easily tweak things and we > automatically benefit from upstream improvements. If we do pydata, we join > with our counterparts Numpy, scipy, pandas, etc. and it keeps us connected > nicely to that community and when people jump around the scipy ecosystem docs > they get the same (or similar) experience. RTD theme, by far, is the most > used because it is the default theme on their service and there is a company > that spends a lot of dev time on it. RTD is quite valuable and gives a > uniform experience across a large set of python projects. Furo and book are > likely used the least and have the smallest dev communities. Furo, as I > understand, is essentially a one man show. It looks nice now, but may not be > a good long term solution.
I agree that the bus factor is a downside to Furo. However, I'm not too worried about it given that it's not all that hard to change the Sphinx theme. Any customizations would have to be redone, but it took me about a day of work to restyle Furo (and honestly someone more familiar with CSS could have done it much faster). And there are ways that Furo could have made restyling easier than it was, so potentially restyling a hypothetical future theme could be done even easier. The styling (colors, font choices, very basic CSS changes) are easy to make. What's hard to do is to change how the theme works at a fundamental level. That's why one of the primary things we looked at was the behavior of the sidebars in the different themes. This is not something we can "fix" ourselves with some CSS. We are really just stuck with however the theme handles things. Here Furo had the best behavior: for instance, the right sidebar always being expanded, which was noted in the survey as a plus. I would like to avoid things like custom Javascript on the docs site, as it becomes unmaintainable given that most SymPy developers are not frontend developers. In general, the Furo theme seems to have had a finer attention to detail than the other themes. We have a lot of docs and they exercise a lot of corner cases that the other themes don't seem to have been designed around, but Furo handles them correctly. As an example, look at how the different themes' sidebars handle the very long section names on the active deprecations page. Book and Pydata add a horizontal scrollbar to the sidebar: https://bertiewooster.github.io/sympy-doc/book/explanation/active-deprecations.html#sympy-stats-discretemarkovchain-absorbing-probabilites https://bertiewooster.github.io/sympy-doc/pydata/explanation/active-deprecations.html#sympy-stats-discretemarkovchain-absorbing-probabilites Readthedocs just truncates the long names: https://bertiewooster.github.io/sympy-doc/rtd/explanation/active-deprecations.html#sympy-stats-discretemarkovchain-absorbing-probabilites Furo word wraps the text: https://bertiewooster.github.io/sympy-doc/furo/explanation/active-deprecations.html#sympy-stats-discretemarkovchain-absorbing-probabilites The Furo behavior is clearly the best, and it suggests to me that the other themes were not ever tested on this sort of thing. > > Jermey and Aaron concluded that Furo was the best choice, but I hope these > other aspects are considered too. We're a big project and even if Furo > currently has the best looking design of the four, there are other non-design > factors that are also quite important and, IMO, outweigh the 0.1 point rating > differences in the comparison of the designs. The decision to use Furo isn't completely final yet. So if you want to make the case for one of the other themes, you still can. Aaron Meurer > > Jason > moorepants.info > +01 530-601-9791 > > > On Sat, Feb 26, 2022 at 1:24 AM Jeremy Monat <jemo...@gmail.com> wrote: >> >> Hello SymPy community, >> >> SymPy ran a user survey about its documentation theme from February 5-19, >> 2022. The primary purpose of the survey was to guide the selection of a >> Sphinx theme for the SymPy Documentation at https://docs.sympy.org. We thank >> everyone who took and shared the survey. >> >> Even though the survey is no longer open, we still welcome feedback on >> SymPy's documentation. Feel free to reach out to us on the mailing list, or >> in the Github issue to change the Sphinx theme. >> >> I have written up an analysis of the results at >> https://www.sympy.org/sympy-docs-survey/2022-theme-survey.html (thanks to >> Aaron Meurer for some analysis code, and posting the analysis there). The >> source code for the >> Jupyter notebook can be found at https://github.com/sympy/sympy-docs-survey. >> I >> have included a summary of this analysis here. >> >> A total of 22 people responded. The survey was done on Google Surveys and >> was shared on the SymPy public mailing list, the @SymPy Twitter account, and >> a SymPy discussion on GitHub. The survey consisted of 14 questions, all of >> which were optional. The results of these responses are summarized here. We >> would like to thank everyone who took and shared the survey. >> >> At a high level, there are three main takeaways from the results. >> >> The themes can be divided into three ratings categories, where the rating >> scale was 1 (Not very useful) to 4 (Very useful): >> >> Highest: Furo at 2.95. >> Middle: PyData and Book, nearly tied at 2.85 and 2.86, respectively. >> Lowest: Read the Docs (RTD) at 2.47. >> >> Most comments about themes, both likes and dislikes, were about formatting, >> look and feel, and navigation. >> >> We should proceed with the Furo theme, customizing it to address >> respondents' dislikes about its formatting. We can keep the PyData and Book >> themes in mind as backup options. >> >> Again, I would like to thank everyone who took the time to fill out this >> survey. It really helps us to have your feedback. >> >> Jeremy Monat >> >> -- >> 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/ae6935a1-d638-4265-a094-bd59f1dfc643n%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/CAP7f1Aidk%3DK_hNciDukWPUM4V6hUNxZXDMkQm-%3DMnR5WcnNspA%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%2BUOV6t%3DgYFqsSxpOs3XuhrtskhFJ0WC_SBMHm2-tvobQ%40mail.gmail.com.
