Write some examples

[choldgraf]

It would be great to see examples of how you imagine these directives working so that folks can try it out!

also cc @jni and @stefanv who I think would be interested in this tool for their Elegant SciPy book?

[jni]

Ha! I'm excited about this but the docs were, um, not what I expected. 😂 Is the idea behind this extension what I expressed in jupyter-book/jupyter-book#455 / jupyter-book/jupyter-book#835?

[choldgraf]

I'm not sure, this package is super super young, but maybe @najuzilu can check out those issues and see if she thinks those ideas are in scope for this package?

[najuzilu]

Thanks @choldgraf for opening this issue.

An exercise directive can easily be initiated by the following pattern: {exercise}. It takes in an optional title and options such as class, label (for referencing throughout the docs), and nonumber flag since the default numbering for these directives is true.

Similarly to the exercise directive, a solution directive links to a specific exercise directive. It can be initiated by the following pattern {solution} and takes in a required argument - the label of the exercise directive it links to- and other options such as class and label.

Going over @stefanv's issue, it looks like the one feature missing from the current implementation is the ability to hide (toggle sounds more appropriate) directives. One could achieve this by wrapping the directives with a toggle directive. I can see how this implementation could be painful to incorporate if you want all solutions toggled, so I would suggest incorporating two configuration keys to toggle all exercise and all solution directives (toggle_exercise_directive and toggle_solution_directive). We can set these config values to false so the user would need to introduce them in conf.py if they wanted to toggle either directive.

I would also suggest we incorporate toggle as a directive option to override the behavior of specific directives. How does this sound?

I should also address the need to hide such directives. We have already discussed the possibility of introducing a configuration value to hide all solutions (similar to remove-cell option for code-cell block). If necessary, we can introduce a hide configuration key for each directive.

I like @jni's suggestion. Just to clarify, would the exercise directive appear twice, once in the book's content and again in the appendix?

[jni]

Just to clarify, would the exercise directive appear twice, once in the book's content and again in the appendix?

Yup, that's exactly right!

[jni]

And thank you! 😊 🙏

[choldgraf]

I wonder if we could add another directive like {exercise-paste} that would allow you to refer to a label of a pre-existing exercise and paste it in the new location. This would let you have "one source of truth" for exercises.

[jni]

My idea was rather to have a global config (or similar) to either copy the exercises over or only move the solutions. Definitely there should only be a single source of truth!

[choldgraf]

maybe another option is to have a :source: option in the {exercise} directive. If :source: is given then it is assumed it should point to a label of another exercise and will just copy over the content. That way we don't need another directive

[najuzilu]

Just want to give you all a heads up that I'm going to tackle these ideas next. :-)