Re: Invalid link generation for equations

[Shuah Khan <skhan@linuxfoundation.org>]

On 3/25/26 14:23, Jonathan Corbet wrote:
> [Adding Konstantin and Mauro, in case anybody has any thoughts...]
> 
> Kevin Brodsky <kevin.brodsky@arm.com> writes:
> 
>> Hi,
>>
>> I have noticed that links to equation images are not generated correctly
>> on docs.kernel.org. For instance, Documentation/mm/memory-model.rst has:
>>
>>      .. math::
>>      
>>         NR\_MEM\_SECTIONS = 2 ^ {(MAX\_PHYSMEM\_BITS - SECTION\_SIZE\_BITS)}
>>
>> The generated HTML [1] shows the source code instead of the rendered
>> equation because the link to the image [2] is broken. [3] does however
>> exist. The issue seems to be that the link is relative to the root, even
>> though we are in a subfolder (mm/ here).
>>
>> Given my non-existent knowledge of Sphinx I have no idea what the fix
>> might be, but I thought I'd report this at least :)
>>
>> - Kevin
>>
>> [1] https://docs.kernel.org/mm/memory-model.html#sparsemem
>> [2]
>> https://docs.kernel.org/mm/_images/math/d99368220bfdedf1a888b1c09eb7236a8c87d079.png
>> [3]
>> https://docs.kernel.org/_images/math/d99368220bfdedf1a888b1c09eb7236a8c87d079.png
> 
> OK, so this is more than passing strange...I can't reproduce that
> problem locally.  The HTML I get is:
> 
>    <img src="../_images/math/d9936822[...]
> 
> On docs.kernel.org, instead:
> 
>    <img src="_images/math/d9936822[...]
> 
> Note the missing "../".
> 
> I will confess that I don't have a great understanding of how imgmath
> works and how that link gets set.  We could "fix" the problem generally
> by setting imgmath_embed=True, but it would be good to understand what's
> actually happening here.

Respect SPHINX_IMGMATH (for html docs only) in Documentation/conf.py
might explain why imgmath_embed=True works?

# Load math renderer:
# For html builder, load imgmath only when its dependencies are met.
# mathjax is the default math renderer since Sphinx 1.8.
have_latex = have_command("latex")
have_dvipng = have_command("dvipng")
load_imgmath = have_latex and have_dvipng

Without setting imgmath_embed=true, math_renderer is mathjax which is
default since Sphinx 1.8

This is based on quick read - I can look into it some more.

thanks,
-- Shuah