Can we color boxes differently?

[bast]

Now: "challenge" and "discussion" and "callout" and ... are all blue.

[rkdarst]

I really agree and would like to, but wasn't confident enough to come up with a color scheme myself. But it will be easy to add it, if someone can find some good colors. (prototype is already in the css file, we just need the colors: sphinx_lesson/_static/sphinx_lesson.css, see bottom and copy instructor-note example for other classes).

[rkdarst]

List of custom directives: https://github.com/coderefinery/sphinx-lesson/blob/master/sphinx_lesson/directives.py#L62 (one could also add extra classes here, not sure what happens when they clash...) Where to adjust colors: https://github.com/coderefinery/sphinx-lesson/blob/master/sphinx_lesson/_static/sphinx_lesson.css (copy instructor note at bottom)

[mehimself]

Here is adobe's gadget to pick balanced colors: https://color.adobe.com/create/color-wheel

you can even extract a color theme from images (screenshots?)

[robertodr]

See also ColorBrewer: https://colorbrewer2.org/#type=sequential&scheme=BuGn&n=3

[rkdarst]

For this, my general thought is:

• sphinx-rtd-theme provides ~4 colors by default (blue, green, red, orange) which seems like a good number
• think of which sphinx-lesson box should map to each of those colors (by simple css class specification)
• so that we do the least amount of special casing, and are most compatible with any theme. If this is useful, I don't know, but seems like a good principle...

[robertodr]

I'm playing around a bit with this while preparing a lesson. I'm also adding some directives which might be generally useful. I'll keep you posted and maybe I can contribute a PR with these changes.

At the moment, sphinx-lesson does not play very well with other themes. It kind of works with sphinx-book-theme, but gives hideous results with pydata-sphinx-theme.

[rkdarst]

Hm, good to know. I just tried pydata-sphinx-theme, and it seems the main problem is the top-bar is too wid. Do you see other problems? One thing someone could do is only enable the extension `sphinx_lesson.directives` and/or `sphinx_lesson.md_transforms`, instead of `sphinx_lesson`. This won't bring in some of the other optional formatting stuff, which should (theoretically) increase compatibility more. But it should let the directives be used in other projects. I guess there are likely some other poblems to be resolved in that, though... Also, the sphinx_rtd_theme_ext_color_contrast is active by default in the conf.py file. This could very well cause some other themes to break a lot (but not, it seems to me, the pydata theme). (the above is for reference, if someone is ever checking for theme compatibility goals)

[rkdarst]

I just found some old uncommitted test I did, where I had "challenge" and "solution" derive from "important". If you've already got a better solution, this can be closed without using it. The previous carpentries theme had a lot of directives, many of which we didn't use. When re-designing things, we should think about what they did, how it is or isn't useful, and how we want to be different. I haven't done any of this yet, I would be inclined to accept anything well thought out. Is a discussion where we invite a broader group of people useful?

[bast]

I would like to limit the number of directives to what "we" need. To not suffer from YAGNI and carrying the legacy backwards compatibility backpack.

But a broader discussion on this is useful.

[rkdarst]

By the way, when picking colors, I also run it through some web accessibility checker to make sure the colors are OK (AA level). I think this is what I used before: https://wave.webaim.org/

[bast]

I am also adapting this for my new lesson. I think we should:

• provide a basic set which is not all blue
• document how to override it (it's easy once you know how/where)
• reduce the number of directives
• document how you can add more directives locally

[rkdarst]

I agree. And I think now we have enough different use cases that we can think about this. Can everyone interested give your thoughts on what principles to use, and what directives you suggest?

Built-in directives (ReST/Sphinx) include:

• ReST/docutils: important, attention, hint, caution, tip, warning, danger, error.
• Sphinx: note, warning, seealso, (versionadded, versionchanged, deprecated)

At reast sphinx_rtd_theme has four default colors, but I think I have seen a similar system in other themes but it is my no means guaranteed. I think the more compatibility we keep with other themes, the better (even if it doesn't work yet). Perhaps an easy way to do this is to try to inherit from these roles, rather than define our own new colors, as much as possible:

• blue (most things)
• green (important, hint, tip)
• yellowish (warning, attention, caution)
• red (danger, error).

So, please comment!

[rkdarst]

And for reference carpentries blocks:

• code: error, warning, output, source
• admonitions: callout, caution, challenge, checklist, discussion, keypoints, objectives, prereq, solution, testimonial

[robertodr]

For our (ENCCS) purposes we've added (see here https://github.com/ENCCS/cmake-workshop/blob/main/content/custom.py):

1. signature (green with wrench emoji, toggle-shown, dropdown) for function signatures
2. parameters (green with laptop emoji, dropdown) for function parameters
3. typealong (grey with keyboard emoji, toggle-shown, dropdown) for exercises where the instructor types and shares their screen.

[bast]

• Please not prereq. It is inconsistent with all the rest. If, then prerequisites.
• callout do we need it? What is it? I only learned this word from Carpentries lesson template.
• Let us add: instructor-notes (but I guess it is there?)

[rkdarst]

Here is my proposal:

We have three base colors (blue, green, yellow, red). green/red is bad for color preception purposes, also "red" seems rather extreme and thus I don't use it often.

Blue: admonition (general class), most everything by default gets this.

• objectives, keypoints, quesitons (if still used). These are some of the few I actually use, but I am wondering if they should be eliminated. At least, these are the only ones I sometimes use.
• advanced (new). drop-down, hidden by default.

Green: "Take an action", derived from "important". This is everything which a person should do. This includes "Exercise" and "Homework".

• type-along (new)
• exercise (new)
• homework (new)
• solution (while technically not a "do this", maybe it's best to make it match? otherwise blue)
• Note that exercises/type-alongs can be long, perhaps a whole section/episode. I propose a convention of only tag the starting point in this case, not the whole thing (where making everything green has no purpose).

Yellow: "Important". Important things to remember. No new directives here, warning is sufficient for now.

• warning (base Sphinx directive, nothing new here)

Red: "Danger", nothing new here

• danger (base Sphinx directive), not used often.

Grey: "Not important, don't read" (as we have now)

• instructor-note (already exists)

Primarily we distinguish between the types of boxes by the emojis, which could be improved.

As for general extendability, anything can be done with a basic admonition directive. For example, prerequisites can be (as defined by sphinx-lesson):

.. prerequisites::

   Content

Or (using nothing but base ReST):

.. admonition:: Prerequisites

   Content

One difference in regular ReST is that "admonition" accepts a title, but other directives don't. I made all of our custom directives accept a title, but if it's not given, then it has some default one (usually the same as the directive). I think this is a useful default, but may have some issues with confusion because it's non-standard!

[rkdarst]

@bast re: callout: "callout" was just from carpentries template when I copied everything. I guess we should leave some aliases (even if not documented) for purposes of conversion.

I think they have a different philosophy where learners don't really see things and almost everything is type-along by default, so the concept of exercise or type-along isn't so relevant to them, thus the difficulty in adapting their default to us. Perhaps I should check again to see what they have...