Fix #317 equation lables

[Blendify]

Fix https://github.com/rtfd/sphinx_rtd_theme/issues/301 this fixes this issue and hides the headerlink until hovering however, the header link is not showing up when it is set to float to the right. Any help on fixing this would be appreciated.

[agjohnson]

Can you provide examples of before and after this change? It helps more than looking at the style rules.

[Blendify]

Before:

After:

[agjohnson]

I like the placement of the footnote better, that makes much more sense :) When I get a chance I can try to replicate the issue. I'll assign myself, but anyone else feel free to chime in here.

[ibell]

This is a big issue for me with this theme, and I'm looking forward to this PR getting merged.

[hagenw]

The header link is not showing up during mouse hover, because the .MathJax_Display element covers the number. If you set its width from 100% to a smaller value like 90% its working. But then the float is no longer working as expected for small screens and long equations as the number gets covered by the equation.

I implemented a version placing the equation number to the right without float, but with absolute positioning which has the advantage that we can then vertically align the number. A full example can be found at http://sfstoolbox.org/en/mathjax/nfchoa/.

In addition to the number placement, I added overflow scrolling to solve the problem with small screens.

Finally, I replaced the header link symbol by the symbol used by RTD similar to the hack in the RTD headerlink section.

Here is the full CSS:

div.math {
    position: relative;
    padding-right: 2.5em;
}
.eqno {
    height: 100%;
    position: absolute;
    right: 0;
    padding-left: 5px;
    padding-bottom: 5px;
    /* Fix for mouse over in Firefox */
    padding-right: 1px;
}
.eqno:before {
    /* Force vertical alignment of number */
    display: inline-block;
    height: 100%;
    vertical-align: middle;
    content: "";
}
.eqno .headerlink {
    display: none;
    visibility: hidden;
    font-size: 14px;
    padding-left: .3em;
}
.eqno:hover .headerlink {
    display: inline-block;
    visibility: hidden;
    margin-right: -1.05em;
}
.eqno .headerlink:after {
    visibility: visible;
    content: "\f0c1";
    font-family: FontAwesome;
    display: inline-block;
    margin-left: -.9em;
}
/* Make responsive */
.MathJax_Display {
    max-width: 100%;
    overflow-x: auto;
    overflow-y: hidden;
}

[hagenw]

Updated the css example to include a fix for Firefox, see https://github.com/jahn/MITgcm/commit/3479d99e4f2cfdc2815d5f8bd5432a9a4d9c2468 for an alternative solution.

[jahn]

Alternatively, one can tie visibility to the entire .math element. This also seems more logical. The following complete example works for me:

.eqno {
    margin-left: 5px;
    float: right;
}
.math .headerlink {
    display: none;
    visibility: hidden;
}
.math:hover .headerlink {
    display: inline-block;
    visibility: visible;
    margin-right: -0.7em;
}

Note that the link symbol is moved out into the margin. Otherwise, it will also be covered by .MathJax_Display and not clickable.

[hagenw]

This is indeed a good alternative and more in line with the behavior of the section permalinks.

I decided against it as I don't see a possibility to influence the vertical alignment of the equation number (it is always at the right top of the equation). The vertical alignment in my example is also still not perfect as it is not the same as in LaTeX, but it looks already ok.

What is good about using float is that the equation number moves above the equation if we are running out of space.

Another difference is that the equation link becomes visible in your case as soon as the mouse hovers the equation. This is in line with the header links and maybe a user would expect it. But I'm still not sure if it is the best behavior for a page with lots of equations. I think it produces less distraction if the link symbol only pops up if you hover the equation number. On the other hand it is not obvious to a user and she might not be able to detect it herself.

[jahn]

Yes, I like the vertical placement in your solution better (but baseline alignment would be even better). What I didn't like is that one has to hard-code the maximum width of the equation number and that all equations move slightly off-center horizontally (because of that hard-coded width), regardless of whether they have an equation number or not. One also looses a fair amount of space on small screens if one has to set a large maximum width for equation numbers.

It would be great if one could have better vertical alignment without having to reserve space for equation numbers.

[nosarthur]

I still see this problem in my sphinx document (compiled with sphinx-rtd-theme-0.4.0). What is the earliest release to include this fix?

[borisalmonacid]

its' ok ?

[danabe74]

To tell the truth, this is one big blemish on an otherwise very nice theme. I have a hard time selling the current html output to my scientific peers. An equation label above the equation is just unheard of. My apologies for the harsh words, I truly wish I could help out instead of complain.

[ax3l]

@Blendify @agjohnson is there anything to do to push this PR further? :) I think the required information were provided and there are further suggestions from @hagenw in the comments

[Blendify]

Looks good but we need someone else to review the patch before it lands.

[Cory-Kramer]

This is still an issue as of sphinx-rtd-theme==0.4.3. Any update regarding a fix to the equation number alignment/formatting?

[ka-bo]

This is still an issue as of sphinx-rtd-theme==0.4.3. Any update regarding a fix to the equation number alignment/formatting?

Unfortunately, yes!

[agjohnson]

Apologies, I haven't had time to look into this one more -- the mathjax stuff is new to me. Does html5 writer or theme release 0.5.0rc1 alter any of this?

[ka-bo]

Thanks. I just tried sphinx-rtd-theme release 0.5.0rc1 and the problem persists.

[benjaoming]

This PR is still building and the changes still show up nicely.

1. The CSS additions would have to be reworked for our SASS source
2. Then tested
3. We would probably also want to note something in changelog.rst

[eebasso]

I think I have found a simple solution as described here: https://github.com/readthedocs/sphinx_rtd_theme/issues/301#issuecomment-1894847212

The corresponding additions to the _theme_mathjax.sass file would presumably be:

span.eqno
  float: right

  a.headerlink
    position: relative
    z-index: 1

It's possible that a.headerlink should be replaced with just .headerlink. Not sure which is better, but both work as far as I can tell based on my testing.

I think the key here is z-index, which makes the headerlink appear above the displayed equation as opposed to being hidden by it.