👌 IMPROVE: Replace sphinx-togglebutton with built-in functionality #446
Conversation
This allows for tighter integration with myst-nb: - Nicer rendering of the hidden content - Customisation of the hide/show prompts The implementation uses "static" details/summary HTML tags directly + CSS, similar to sphinx-design, rather than the JS implementation used by sphinx-togglebutton.
Codecov ReportBase: 81.37% // Head: 81.74% // Increases project coverage by
Additional details and impacted files@@ Coverage Diff @@
## master #446 +/- ##
==========================================
+ Coverage 81.37% 81.74% +0.37%
==========================================
Files 29 29
Lines 2572 2630 +58
==========================================
+ Hits 2093 2150 +57
- Misses 479 480 +1
Flags with carried forward coverage won't be shown. Click here to find out more.
Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here. ☔ View full report at Codecov. |
|
Please give others a chance to review PRs, especially if we are changing UI/UX, and especially if there is not a linked issue that already has discussion and agreement on a change - at least one global working day unless it's something really mission critical to merge quickly. This seems OK to me - it's pretty nice to be able to configure the text and to have code cell-specific text. Two design comments: sharp edges: The "rounded corners on top and sharp edges on bottom" UI feels a little bit awkward to me - my vote would have been to just style these like regular buttons rather than have the sharp edges. This feels clunky in particular in the output cells:
That said, I'm not a UI/UX expert so this is something we should just get feedback from others on over time. a11y: I suspect that the color contrast of the font isn't strong enough for accessibility / vision-impaired people. Can we increase the contrast of the text?
|
|
Heya @choldgraf I did indeed need it for an actual live demonstration I gave yesterday 😅 https://aiida-qe-demo.readthedocs.io/en/latest/2_bands_workflow.html
The problem is there was no real agreement on sphinx-togglebutton in the first place. This is better, but still when you actually use this in practice, you end up with many
which is absolutely not clear to the user what it actually is, until they click it with the new implementation (post #450) I'm really happy with the UI:
(expanded) It is now clear, from both the green margin and the prompt, that these are all related to code cells. For
the goal of the UI is to indicate that this is only the top of the code cell, and that clicking on it will reveal the rest |
|
I think we can discuss elsewhere, but the point isn't to debate the specific UX of this implementation (the "sharp edges" approach has grown on me and I think it looks nice as well). I think these are the two main points:
Obviously no project follows both of these perfectly, but we need to begin following practices like this more closely as we grow these projects beyond a small grant-funded team. To your point above - we didn't follow this process for |
yep I completely agree on all of this, and thats why you need to stop doing anything else you're doing on EPB and make your MEP (https://github.com/executablebooks/myst-eps) on the steering council 😉 |
|
Just to be clear, in my opinion we don't want a steering council to make UI/UX decisions about individual repositories in the organization. I think it's important to delegate and distribute our decision-making so that many decisions are made close to the place where the work will happen. The steerco is meant to define strategy, policy, and steward the community. In this case, I think a steering council would decide on the policy for "what process to follow when gathering community feedback for decisions", not on the decision about whether to use sharp edges on code blocks. Fortunately I think that we can start to improve our policies and practices without waiting for a steering council to make a formal proposal. |
|
I but it defines the top level process of how this is done, and also probably top level goals design decisions for UI/UX. both of which can be refer to when we have these conversations |
|
Hey, sorry for adding to the off-topic conversation, but I would like to think that I have something to add. But enough about me, I actually did see that this PR was opened and also had the same thought as @choldgraf about the sharp edges and the color contrast. So I would like to argue that it is nice (at least for me) if one can follow the decision process of UI changes or any updates at all really.
I would also like to piggy-back on this comment. But before I give the wrong impression, please understand that I am very grateful for all of your work and that I am a huge fan of the executable book project, and it would be a dream come true to work on executable book projects via grants. 😄 Sorry, the text became A LOT longer than I thought... 😅 Kai's way too long feedbackExternal project experienceTo keep it real, I would like to talk about a thing I've implemented: I've implemented a custom preprocessor to parse the notebooks and to inject tags via code comments (nbdev style since I personally think it is an important feature when coming from nbdev). TL;DR: I think every executable books project page should have a community page where external projects can be advertised to minimize duplicated work and let developers feel like they are giving back and not just solving their problems in a public repo. Discussion Forum experienceAnd as I also mentioned the "Discussion Forum", I would also share my personal experience: TL;DR I personally keep forgetting that the GitHub Discussion Forum exists. Maybe more advertising could help? Or better communicating what can be asked in the forum and that answering those questions is a valuable task? Project splinteringAnother issue I have is that the organization has many documentation websites and that it is hard to communicate external projects to the end-user. TL;DR: Due to the many projects under the executable books umbrella, it is hard to work on a 'lower-level' and see how external work can be 'advertised' to the end-user. I have no solution but I think it should be discussed. Especially when we start to draw a line between "implementation details" of dependencies like MyST-Parser/Sphinx. Maybe every page could have a toolchain section that "visualizes" the different levels (like visual style of jupyter book? Maybe videos can help? Like I said, I don't know. Large tech-stackIMHO the above points also lead to a high entry barrier to contributing to the MyST-NB/Jupyter-Book repositories. TL;DR: Jupyer-Book is a very complex piece of software. To make it easier for contributors, I think there is a need for more 'developer' specific tutorials. Maybe this could be crowd-sourced, but then it should be 'advertised/endorsed' by the executable books forum. But especially the low-level stuff (Sphinx/testing related) is something I think many are missing the expertise on and is something that would best be tackled by the maintainers themselves. SummarySorry for writing so unbelievably much. I didn't intend to write all of these details 😅 Cheers! |
Thank you for this feedbackKai - I want to express my strong appreciation for this feedback. It is really hard to notice if a project is hard to contribute to, precisely because you don't tend to talk to the people that aren't present. I think one of the most important questions an open project can ask is "who is not in the room right now, and why not?" Your post provides a number of helpful clues and ideas as to why others may not be able to contribute. As we begin to move the project beyond its initial grant-funded team, I think this will be crucial to improve. My opinion is that if you, a highly-engaged person with development capabilities, feel this way, then there are many, many more people who feel the same way. I'm going to provide a few quick responses below - some of them are explanations for points you make but I just want to re-iterate that these aren't making excuses - I recognize that they are all major aspects of growing a community that we must improve.
I think this is crucial. We must separate the discussion and decision-making process from the implementation process. If we don't do this then it will be very hard for non-developers (or really, non maintainers) to participate in these processes. We have had some discussion of this in the issue below, and I've encoded your suggestions in a comment there there as well. Please provide feedback there if you'd like to see any refinements!
This is an interesting idea - you think it'd make more sense to delegate this to each sub-project rather than have one centralized place for it?
Agreed - one way that we could resolve this is by using a standardized theme across all of the repositories. This is similar to what Dask does. That way they have the same top-level links on any of their documentation pages. Either way, I agree that we should make it clear where to have general discussion in each repository. I've opened an issue to track this here:
Totally agree - at least we could have a centralized place that explained the whole stack and all of its components. This is something that @mmcky has been interested in doing as well, and I know that @rowanc1 likely benefitted from conversation like this as the curvenote team was onboarding as well. I've encoded this suggestion in this issue, please suggest there if we should refine something:
Also agreed here. I believe this is another thing that @mmcky has been interested in for a while now. Here's one issue where he's tracking this: I think that your suggestion here is slightly more specific, so I've also encoded it in this issue here:
Good question! Folks on the EBP team are trying to figure this out as well :-). I think that some things are starting to settle into place. Our current goal is to build out the JavaScript implementation of MyST in order to see how difficult it is and what parts of the Jupyter Book stack can be replicated with an implementation that is simpler than Docutils/Sphinx, and integrates more easily with Jupyter. We'd then hope to maintain both the Python and the JavaScript implementations, but define MyST as a community-governed standard that can be re-used across many projects and implementations. There are some ideas about this at the end of a recent talk I gave on Jupyter Book at the NumFocus conference: I think what we should do is open up a discussion about some of these ideas in order to invite community feedback...thus far they haven't been crystallized yet but I think they are starting to take shape. You can also preview some of the JavaScript work in these two docs sites: And eventually we will need to figure out how these fit in with the project's "meta" documentatoin: OK I hope that this was some helpful extra context, I am more than happy to discuss with you. I think that making this project more inclusive and adopting healthier asynchronous discussion and development practices is crucial to its success. I want to re-iterate how much I appreciate your thoughtful and helpful comment. |
|
One other note: I think that many of the challenges that you've described are also in-part because we have not done a good job of growing the initial grant-funded team to include broader participation from the community. This is particularly true for roles like stewarding community forums, triaging and guiding issues, etc. I believe this is one direction that the project should prioritize funding that it gets in the future, but I also think we need to grow our volunteer contributor base in this direction as well. I welcome any suggestions you might have for how we can make it easier for others to contribute directly to the project in whatever form they wish. |
|
Thank you for your kind words!
Yes, I am very much aware of the js work from the curvenote team, as I saw some of your discussion in the meta repo, I think. But this splintering across languages is exactly what makes me worried as a (potential) contributor. I do not have any experience with actually packaging and distributing Rust within Python/JS, but it seems like more and more projects (polar for example) utilize this approach. And there is a lot of advertisement about WASM (I know that this has been advertised for years now), and for an outside observer, it seems like the trend might be converging towards WASM+Rust for quite a few projects. I am heavily biased though, as I am very interested in this direction and am not a friend of JS. I understand the heavy connection towards the Jupyter project and their (totally obvious) link to JS, especially because they are doing so much in the Frontend and are working with the DOM. Ok, I just looked at the mystjs page and it has changed a lot since I last looked at it. I will never be a fan of JS, and I will never be objective when it comes to this language. I guess you will hear from me again at some point 👍 Cheers |
I thought about this some more, and I think that I don't have a strong preference. The single page just has to be discoverable for users that are looking at the MyST-NB documentation, for example. Feel free to move this to a separate issue/discussion. |
|
thanks for the feedback @kai-tub
I'd note that I have created https://github.com/executablebooks/myst-eps, precisely for this underpinning design and strategy documentation. |
|
👍 Yes, I agree. |
This allows for tighter integration with myst-nb:
The implementation uses "static" details/summary HTML tags directly + CSS,
similar to sphinx-design,
rather than the JS implementation used by sphinx-togglebutton.