Can you make a sphinx theme be a child of a parent theme, such that we can easily update furo without having to fork and customize furo? If all we are doing is css overrides, I suspect that is possible.
Jason moorepants.info +01 530-601-9791 On Thu, Mar 24, 2022 at 3:24 PM Nicolas Guarin <nicogua...@gmail.com> wrote: > I agree that the demo site is looking great. Although, I think that > sharing a theme with other projects might be something desirable. > > On Tuesday, March 22, 2022 at 3:46:02 PM UTC-5 moore...@gmail.com wrote: > >> Aaron, >> >> I browsed around the demo site. It is looking quite nice! Great job. >> >> Jason >> moorepants.info >> +01 530-601-9791 <(530)%20601-9791> >> >> >> On Tue, Mar 22, 2022 at 8:59 PM Aaron Meurer <asme...@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 <(530)%20601-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 <(530)%20601-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+un...@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+un...@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/524b24d0-416f-477f-a3a8-22eab1141ee4n%40googlegroups.com > <https://groups.google.com/d/msgid/sympy/524b24d0-416f-477f-a3a8-22eab1141ee4n%40googlegroups.com?utm_medium=email&utm_source=footer> > . > -- 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/CAP7f1AjMfCmd-%3D3PiM9Er%3D%2BCMeSSY%3DXsVjOfKZieNMz8D_GX3g%40mail.gmail.com.
