RunestoneComponents
RunestoneComponents copied to clipboard
RunestoneInteractive
Display numbers for activities
The div_id for each Runestone Component is used in several places in the book as wells as the instructor interface. While it is important that each component has a unique identifier, it may not be necessary for instructors to recall those.
Most instructors would be much happier if we could consistently number the in book activities use the following scheme chapternum.subchapternum.exercisenum
The challenge in implementing this is that Sphinx does not process chapters/subchapters in the order that we think of them, and hence we don't know when sphinx is processing a file what the correct number would be. I don't want authors to have to be responsible for numbering, that should be automated. And we have, automated the numbering of chapters and subchapters. But it comes at the end of the build process. We do know the correct number for an activity on the page as pages are processed from top to bottom 😄 . We can also embed this number at build time.
I propose we standardize the components to insert a bit of template code that can be resolved at page load time. like this:
Activity: {{ =chapnum }}.{{ =subchapnum }}.X ComponentKind (ac2_14_1)
In the Question pickers we can append the numbers to the name that is displayed to make it easier for instructors to find what they are looking for.
This won't work for me, and might limit the flexibility of others -- numbering is fairly broken in the book I write. I chose to use Sphinx's autonumbering facility for sections/chapters/subchapters, which means chapter/subchapter numbers in the question picker of the instructor interface make no sense.
So the chapter / subchapter numbers in the chapters and sub_chapters tables do not match the numbering you see in the book? That is not the case for most of the books that I build...
Unless you are including more than one subchapter in the same file, then yes, I can understand how that causes problems. But if you "follow the rules" of one file == one subchapter then the numbers will stay in sync. I understand that doesn't always seem like the best organization, and I know others would like subsubchapters. I think that would take a long hard discussion to redesign what we do with chapters and subchapters to support that.
That's the basic problem for me: the literate programming exercises require a page of their own; they can't be embedded on an existing page. So, for a given subchapter, I have several subsubchapters consisting of LP exercises.
I understand the difficulty of the redesign, and it's not something I really want to tackle right now either. However, I'd prefer not to put more in the book that assumes chapter/subchapter structure, since this will be student-facing brokenness, not just instructor-facing brokenness.
If we do numbering, I'd prefer to base numbers off what the toctree directive's numbered option produces.
But that is how it is working right now, at least for all the books on runestone.academy. The numbers in the chapters and sub_chapters tables match the ordering imposed by the index.rst and the toctree files for each chapter.
We already have an option in conf.py called generate_component_labels that you can set to false to disable numbering of components. So you can have it off if your structure doesn't lend itself to this scheme.
Only by chance, not by actually looking at the underlying variables used to define these numbers.
Component numbering, since it's per-page, works just fine. Adding things in the template for page load would imply these number will always be inserted, correct?
I would choose to frame it as being careful rather than chance.
I was thinking that we would have getNumber return the template string for numbering, which is what we do now. If generate_component_labels is False then its just an empty string with nothing to populate.
I suppose the rightest thing to do is to use the "{{ =chapnum }}.{{ =subchapnum }}.X" as the default and still allow the numbering to be overridden if an author chooses to use the qnum directive to control their prefixes and numbering.
I'm trying to find a solution as this is one of the top 5 things that annoys instructors about using Runestone for making and grading assignments.
I agree that having a coherent numbering system for all questions is important. It makes it much easier for me to at least be able to refer to "Q-5" on a page, instead of "random div_id here".
IMHO, an ideal solution would be to directly adopt Sphinx's numbering system, for two reasons. First, the numbering of standard Runestone books will agree with the Runestone chapter/subchapter structure, so the change would be transparent to most books. Second, this will help Runestone take advantage of the work that other (larger) development teams (Sphinx) do, rather than needs to maintain yet another feature. Third, this will help make the transition away from Runestone's chapter/subchapter structure a bit easier when we're ready to take on the task.
So, would you consider using something more like "Sphinx page number.question number" instead?
You must be thinking of something that I don't know about or understand. I don't know what you mean by Sphinx page number.
I think we are both arguing for the same thing but you for some reason don't believe that we are already there. What we have today is the best implementation I could come up with at the time for matching sphinx's number system. I don't give a crap about the implementation I just want the chapter numbers and the subchapter numbers to match. If you have a better strategy for achieving that please share it.
My apologies -- I'm using terms poorly. Do you have a minute to chat via Google meet? Perhaps it would be easier face-to-face.
Briefly, I propose we use env.toc_secnumbers.get(docname, {}) or something like that.
That is, I propose using Sphinx's existing section numbering system, not using "extra" code that matches it.
I'm happy to discuss further. Maybe tomorrow morning? I'm not sure who will be on the hangout. Liverpool and Man City are playing right now, so my video is busy. 😄
I'm happy you found something where we can get the numbers directly from sphinx, I searched and searched a couple years ago and couldn't find any way of digging that out. That is one of the things that frustrates me most about sphinx is that I feel like most of what I am able to figure out about the internals comes from poking around in the debugger. Maybe you know of some better documentation?
Sounds good. I'll play a bit and let you know what I find.
Sphinx/docutils internals docs are difficult. I end up reading the source/debugging a lot also to find these kinds of things.