Can't link directly to exercises

[rkdarst]

In sphinx, admonition blocks don't generate HTML <hX> links and anchors which can be directly linked to. This has annoyed me, because I can't link straight to exercise blocks. This can be done in the jekyll theme because of how it works (interestingly, because the exercise block isn't structured into a unique type but uses a div + class).

My proposed solution would be to recommend each exercise is in a short section labeled "Exercises: topic", possibly with some intro text about what these exercises mean, and then one exercise admonition for each exercise, with a title describing it.

What do you think?

[mehimself]

is there a way to execute some javascript? We could set the document scroll position from an url (lessonPageUrl#exerciseAlias) and map the alias in the url parameters to unique exercise elements (unique classname?)

[rkdarst]

We can put arbitrary CSS and javascript into sphinx-lesson/_static/, and load it in the HTML head. I do that with some CSS, javascript works the same and I've done it on other sites.

If it's general I can show you how to make a Sphinx extension that others can use (that is what jupyterbook has done), and these are extremely useful.

[mehimself]

It should be general. It allows us to link to arbitrary elements. I will look at plugin generation.

Then we need a convention how to map exercise classNames to #lessonAliases. ..and avoid collisions with possible ids used in lesson pages fx:

.alias_exercise_install_sphinx // exercise class name found at pageUrl#exercise_install_sphinx

But once we develop a plugin we could opt to add a directive for assigning ids to elements... I will look into that

[rkdarst]

By the way, I didn't post this to say we needed to do something about it. Some sphinx modifications are fun, but this one might not be. I think it might be best to not try too hard and decide "this is acceptable", and use more sections instead - that's why I made the issue, to point it out, not that we had to fix.

If there could be a pure-javascript solution, that wouldn't be too hard on the Sphinx side. But since sphinx reads the content, puts it into a document tree, and then writes it out via writers, if the document stuff doesn't have a hook for adding a reference anchor... it might not be realistic to change (or worth the time...).

[rkdarst]

I made an example of another way to arrange exercises and solutions:

https://coderefinery.github.io/sphinx-lesson/branch/rkdarst--sample-lesson-exercises/sample-episode-rst/#exercise-the-general-topic

What do you think? Exercise is now it table of contents (this is an unexpected benefit, this is probably useful). But it does make the exercises take a lot more vertical space.

What do you all think?

[bast]

Example goes to 404.

[rkdarst]

The PR was merged, so now it is here: https://coderefinery.github.io/sphinx-lesson/sample-episode-rst/#exercise-the-general-topic

(I was going to make that a draft PR but forgot...)