Invalid link generation for equations

Invalid link generation for equations

[Kevin Brodsky]

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

Re: Invalid link generation for equations

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 461 bytes --]

On Wed, Mar 18, 2026 at 01:56:24PM +0100, Kevin Brodsky wrote:
> 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)}

I think we can just get rid of the math markup, no?

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: Invalid link generation for equations

[Randy Dunlap]

On 3/19/26 5:06 PM, Bagas Sanjaya wrote:
> On Wed, Mar 18, 2026 at 01:56:24PM +0100, Kevin Brodsky wrote:
>> 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)}
> 
> I think we can just get rid of the math markup, no?
> 

Why get rid of it?
and does that assume that some specific package is installed?

Documentation/doc-guide/sphinx.rst says math expressions can be handled with
imgmath or with mathjax.
I don't either of them installed and this expression seems to render quite well
as a math expression:

<p>The maximal number of sections is denoted <cite>NR_MEM_SECTIONS</cite> and
defined as</p>
<div class="math notranslate nohighlight">
\[NR\_MEM\_SECTIONS = 2 ^ {(MAX\_PHYSMEM\_BITS - SECTION\_SIZE\_BITS)}\]</div>

The "(MAX_PHYSMEM_BITS - SECTION_SIZE_BITS)" is presented as a superscript (power)
of 2.

OTOH, if you are saying that it's readable when just using ASCII text,
I'm OK with that also.

-- 
~Randy

Re: Invalid link generation for equations

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 872 bytes --]

On Thu, Mar 19, 2026 at 08:10:42PM -0700, Randy Dunlap wrote:
> 
> 
> On 3/19/26 5:06 PM, Bagas Sanjaya wrote:
> > On Wed, Mar 18, 2026 at 01:56:24PM +0100, Kevin Brodsky wrote:
> >> 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)}
> > 
> > I think we can just get rid of the math markup, no?
> > 
> 
> Why get rid of it?
> and does that assume that some specific package is installed?
> 
> <snipped>...
>
> OTOH, if you are saying that it's readable when just using ASCII text,
> I'm OK with that also.

I think that's what I mean.

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: Invalid link generation for equations

[Jonathan Corbet]

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

Thanks for the report.

We have all that elaborate machinery for generating fancy formatted
math, it would be best if it works properly.  I am curious, though, if
it's truly broken universally and, if so, how long that has been the
case.  If it's been that way for some time, one might legitimately
wonder why nobody has noticed thus far.

Anyway, will try to look into it soon.

Thanks,

jon

Re: Invalid link generation for equations

[Jonathan Corbet]

[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.

Thanks,

jon

Re: Invalid link generation for equations

[Shuah Khan]

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

Re: Invalid link generation for equations

[Jonathan Corbet]

Shuah Khan <skhan@linuxfoundation.org> writes:

>> 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

We default to imgmath if the requisite utilities (latex, dvipng) are
installed on the system; perhaps that's not ideal, but it's what we have
done for a while.  It all seems to be working as expected, except that
the <img> element has the wrong URI in it.  Strange.

jon

Re: Invalid link generation for equations

[Mauro Carvalho Chehab]

On Wed, 25 Mar 2026 15:11:57 -0600
Jonathan Corbet <corbet@lwn.net> wrote:

> Shuah Khan <skhan@linuxfoundation.org> writes:
> 
> >> 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  
> 
> We default to imgmath if the requisite utilities (latex, dvipng) are
> installed on the system; perhaps that's not ideal, but it's what we have
> done for a while.  It all seems to be working as expected, except that
> the <img> element has the wrong URI in it.  Strange.

Looking at this changelog from Akira:

	6b0d3e7c5888 ("docs/conf.py: Treat mathjax as fallback math renderer")

It mentions that this is kept due to epub output. On a quick search:

	https://github.com/sphinx-doc/sphinx/issues/1570

I'm not sure how this is handled in PDF, but mathjax seems to be
specific for html output only.
	
Thanks,
Mauro

Re: Invalid link generation for equations

[Akira Yokosawa]

Hi,

[...]

I think I found out what is happening.

Sphinx version at https://www.kernel.org/doc/html/latest/ is 5.3.0.

Sphinx version at https://www.kernel.org/doc/html/next/ is 7.4.7, where
math expressions are rendered as expected.

Sphinx 6.0.1, whose changelog at:

  https://www.sphinx-doc.org/en/master/changes/6.0.html#release-6-0-1-released-jan-05-2023

says:

  Bugs fixed

    #10944: imgmath: Fix resolving image paths for files in nested
            folders.

The bug was introduced in Sphinix 5.3.0.

This means Sphinx at https://www.kernel.org/doc/html/latest/ wants an
upgrade.

Thanks, Akira