Furo looks good. If you think the bus factor is not a big deal, that's fine then. It's not as important as an actual dependency of sympy.
> 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. My vote in the survey was RTD. I explained it in the survey my reasoning. But that's all I have to offer for the case. Jason moorepants.info +01 530-601-9791 On Tue, Mar 1, 2022 at 12:50 AM Aaron Meurer <asmeu...@gmail.com> wrote: > 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 > . > -- 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/CAP7f1AhoJaYQtFcjveO_7W0w1qCjXm5iQN6_EB%3D8JW3F5vS%3DoA%40mail.gmail.com.
