Create a sphinx-margin package

[choldgraf]

Background

In a recent Twitter thread, @astrojuanlu noted that the Sphinx RTD theme might also make good use of the margin content in the Sphinx Book Theme.

This looks like the following

and was inspired by the Tufte CSS theme:

Implementation

There's nothing inherently fancy about the Margin, it is basically just this directive that sub-classes the Sidebar directive:

https://github.com/executablebooks/sphinx-book-theme/blob/master/sphinx_book_theme/__init__.py#L257

and then some light CSS to make it pop-out to the right of the main content, with a reduced size and width:

mostly here: https://github.com/executablebooks/sphinx-book-theme/blob/master/src/scss/_page.scss#L509

and a little bit here: https://github.com/executablebooks/sphinx-book-theme/blob/master/src/scss/_page.scss#L127

Future enhancements

Having a standalone extension might make it easier to extend functionality of the Margin directive to allow for things like margin sidenotes, and usage across themes might make it more likely that we uncover edge-case bugs etc.

Question

Would it be useful if we spun out the Margin directive into a separate Sphinx extension like sphinx-margin? It would come with some pre-determined CSS that would behave something like the following:

• The Margin directive would act the same way that it does currently - sub-class Sidebar and then add a margin class.
• When the screen width was above XXX amount, then do the following:
• Content with .margin, .margin-caption, or tag_margin classes will have the following properties:
  • ~50% width of main content
  • font size em - .2
  • Float to the right
  • Placed so that the upper-left of the margin block begins at the right edge of the content

If a theme needed to change the behavior, this could be done with theme-specific CSS that takes this extension into account.

That said, I think the big question is whether this could be general enough that it would actually behave consistently across themes. Obviously this would only work for themes that had a significant margin on the right side, though I think this is somewhat common!

Would this be useful?

I am curious if @pradyunsg @astrojuanlu or @ericholscher would find an extension like this useful for re-use across themes, instead of being embedded in the sphinx-book-theme. Moreover, I wonder if you think it is doable or if this is too much CSS shenanigans to get right.

Thoughts?

[pradyunsg]

This sounds good, although I think we should have some way for themes to opt-in to this extension, such that the extension refuses to work if run with an incompatible theme.

One way I can think of opt-ing in, is to use entry_points metadata:

sphinx-margin.compatible-themes =
    sphinx-book-theme = sphinx-book-theme

[ericholscher]

Just as a note, we've had a lot of trouble with hard-coded lists of themes because of forks & customizations. I'd at least make it overridable at the sphinx-config level if possible (eg. work_on_unsupported_theme or similar).

[pradyunsg]

Just as a note, we've had a lot of trouble with hard-coded lists of themes because of forks & customizations.

This isn't a list hard-coded in the plugin. Rather, each theme that wants to work with this would hold metadata saying "I'm compatible with the plugin". But, yea, work_on_unsupported_theme still makes sense regardless of that. :)

[choldgraf]

Thinking about this a bit more - rather than asking themes to "opt-in" via an entrypoint, we could simply use this package to define a consistent class name that would be added to margin notes, and then leave it up to the theme to style those classes however they like.

For example, we might bundle the Tufte CSS rules for single-column sidenotes (https://edwardtufte.github.io/tufte-css/) with this package. This effectively turns sidenotes into "collapsible admonitions", and that should be something we could implement in a theme-agnostic way. Then, in the documentation we could include a section that says "if you wanted to implement the "pop out to the margin" behavior that Tufte recommends, this is the CSS that you should add to your theme.

That way, the base behavior would be the same on any theme, and only the fancier "pop out" behavior would be different for themes that implemented the proper rules for things...

Example

So we could define a consistent (unopinionated) style like:

The in-line {sidenote} directive and role would output:

<label for="sn-demo" class="margin-toggle sidenote-number"></label>
<input type="checkbox" id="sn-demo" class="margin-toggle"/>
<span class="sidenote" id="sn-demo">
  This is a side note. With a number that is added via the CSS `counter` rule.
</span>

and the {margin} directive (and role) would create the following HTML:

<label for="mn-demo" class="margin-toggle">&#8853;</label>
<input type="checkbox" id="mn-demo" class="margin-toggle"/>
<span class="marginnote">
  This is a margin note. Notice there isn’t a number preceding the note.
</span>

And we'd define single-column rules for margin-toggle, marginnote, sidenote, etc, and leave it to themes to define extra behavior for things that would pop out to the margin.

And both would behave like admonitions when outputting to Latex etc.

[pradyunsg]

We could be a bit hacky-ish here and have the class here be sidebar sidebar--margin. This avoids needing to ship CSS in this package, making things a little simpler and more likely to be compatible with other themes -- the package is just the directive and some documentation. If the theme does support margin-style content, they can add in the relevant styles, targeting sidebar--margin. If not, then these just get stylised like the current .. sidebar:: directive which most themes do handle reasonably well (i.e. this package wouldn't need to account for themes' designs, those themes don't have to account for this package's default CSS etc).

How does that sound?

[choldgraf]

That's.an interesting idea. Though I almost think that the sidenote/margin content would semantically be closer to admonition than to sidebar. WDYT?

[astrojuanlu]

Today I re-discovered https://github.com/ulrobix/sphinxcontrib-contentui, which provides something similar: https://sphinxcontrib-contentui.readthedocs.io/en/latest/columns.html

[choldgraf]

wow cool! I had never heard of that!