Aaron, I browsed around the demo site. It is looking quite nice! Great job.
Jason moorepants.info +01 530-601-9791 On Tue, Mar 22, 2022 at 8:59 PM Aaron Meurer <asmeu...@gmail.com> wrote: > An update on this: the Furo theme pull request is now ready for a > final review. The demo site is at > https://www.asmeurer.com/sympy-furo-demo/dev/index.html. I've done > several modifications to the base Furo theme, mostly changing colors > and a few small font tweaks, so please let me know if you see anything > that should be improved style-wise. If you can, please also test the > dark mode (click the sun icon at the top), and on mobile, and try to > look at different types of documentation pages. If something looks > off, there's a good chance I messed up the CSS for it somehow or just > didn't notice it, so please let me know. > > The pull request is https://github.com/sympy/sympy/pull/23159/. Also > if any frontend experts can critique my terrible CSS/Javascript > skills, that would be helpful. > > Note that this does remove the SymPy Live extension from the > documentation, as it's not compatible with Furo. If we can get a > similar extension implemented that uses pyiodide, preferably one that > is maintained by the broader community, that would be great. > > Aaron Meurer > > On Tue, Mar 1, 2022 at 11:37 AM Chris Smith <smi...@gmail.com> wrote: > > > > For anyone else not familiar yet with the "bus factor", I learned from > wikipedia that "The bus factor is a measurement of the risk resulting from > information and capabilities not being shared among team members, derived > from the phrase "in case they get hit by a bus." > > > > /c > > On Tuesday, March 1, 2022 at 2:49:12 AM UTC-6 moore...@gmail.com wrote: > >> > >> 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 <asme...@gmail.com> wrote: > >>> > >>> On Sat, Feb 26, 2022 at 1:11 AM Jason Moore <moore...@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 <jem...@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+un...@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+un...@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+un...@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/94987327-7337-4386-bd6f-112dd5713d97n%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/CAKgW%3D6Kctcx7wCuDyrHuwnpR2rD6eSe95cd_0BgLVen-TqEJPg%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/CAP7f1AhAfZZ847_Q9Nk4iH%3Dj7hOBhkUmTmAC%3D5SL1yjA3YyODw%40mail.gmail.com.
