Bug 14436

If I look at the pattern, I see, that I am still able to to access

ref-machine-features

<div class="section" id="machine-features">
<span id="ref-features-machine"></span><h4><span class="section-number">12.1 </span>Machine Features<a class="headerlink" href="#machine-features" title="Permalink to this headline">¶</a></h4>

This would work for me:

replace:

<span id="document-ref-manual/features"></span><div class="section" id="features">

with:

<span id="document-ref-manual/features"></span><div class="section" id="ref-features">

another example:

1) http://docs.yoctoproject.org/singleindex.html#yocto-project-linux-kernel-development-manual

2) click on permalink for Introduction

http://docs.yoctoproject.org/singleindex.html#introduction

which is wrong

another example:

1)

http://docs.yoctoproject.org/singleindex.html#yocto-project-linux-kernel-development-manual

2) click on permalink of

1.1 Overview

http://docs.yoctoproject.org/singleindex.html#overview

which is wrong

another example:

1) http://docs.yoctoproject.org/singleindex.html#yocto-project-linux-kernel-development-manual

2) click on 1.1 Overview

http://docs.yoctoproject.org/singleindex.html#overview

which is wrong

Since those links are most likely also used internally singleindex.html is most likely broken for all and not just for me since links are not unique. 

With separate manuals things most likely still work. 
The question is how inter-document links are made.
I assume a.html#link and b.html#link is the main difference, since with different html files the same link names can refer to different html docs.

singleindex.html is a single html file and hence it's broken for the case where internal links are not unique.

They need to be unique per html document!

Hi Robert,

Thank you very much for the bug report.

I looked for options in the Sphinx "singlehtml" output, which could address this issue.

The corresponding builder is documented here:
https://www.sphinx-doc.org/en/master/usage/builders/index.html

And the source code is here:
https://github.com/sphinx-doc/sphinx/blob/master/sphinx/builders/singlehtml.py
https://github.com/sphinx-doc/sphinx/blob/master/sphinx/builders/html/__init__.py

What seems to be wrong is the way "permalinks" are created. See "html_permalinks" and "html_add_permalinks" in the https://github.com/sphinx-doc/sphinx/blob/master/sphinx/builders/html/__init__.py file.

There is documentation on https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_permalinks too.

I'll take some spare time to understand the code that generates the singlehtml output and see what's possible to do. This may require to push a patch upstream.

That's better than making sure we have no subsections that have the same name in different manuals.

Thanks again
Michael.

Also wanted to add that the links to top sections on the left bar are unique, so there's hope to implement something similar for individual permalinks.

OK great!

This is what I do:

I download a local copy of the mega-manual and link to it from my slides and I also noticed that if I use a local copy like that from a browser:

file:///home/rber/projects/trainings/framework-3.0/yocto-3.0/mega-manual-new/mega-manual.html

links still refer e.g. to http://docs.yoctoproject.org/singleindex.html#term-Build-Host and not to the relative path.

Not sure this is intentional. It was not the case with the good old doc.

Here's another comment from Robert...

We have the same link (I guess auto generated) multiple times in the html, which I need to patch in order to link from my pdf files to the right one.

Something like that:

Index: final-yocto/singleindex.html
===================================================================
--- final-yocto.orig/singleindex.html
+++ final-yocto/singleindex.html
@@ -32337,7 +32337,7 @@ log into the <a class="reference externa
 <div class="line"><br /></div>
 </div>
 <div class="toctree-wrapper compound">
-<span id="document-kernel-dev/intro"></span><section id="introduction">
+<span id="document-kernel-dev/intro"></span><section id="kernel-dev-introduction">
 <h3><span class="section-number">1 </span>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline"></a></h3>
 <section id="overview">
 <h4><span class="section-number">1.1 </span>Overview<a class="headerlink" href="#overview" title="Permalink to this headline"></a></h4>

The problem still happens with Sphinx 5.1.1
It will need fixing in upstream.

Steps to reproduce:
make singlehtml
open __build/singlehtml/index.html#document-kernel-dev/index
Follow the link to 
Click on the permalink associated to the "overview" section
It goes to another "overview" section elsewhere in the mega manual.

That's because "make singlehtml" doesn't make permalinks unique if there are identical section names in different documents.

Milestone set to 4.2 M4.

Sidenote: this is also an open issue in Sphinx since 2018: https://github.com/sphinx-doc/sphinx/issues/4814.

I don't this it was mentioned here before.

From the issue, it seems that the root of the problem could be docutils, not even Sphinx. 

I looked at the code in `builders/html/__init__.py`, and `ids` are generated by docutils and Sphinx uses them to add the `href` attribute in the relevant html node, so it _not_ generating the attribute.

I doubt there is an easy solution to this unfortunately.

Bulk move of 5.1 M4 to 5.2 M2 as approved by AlexB.

Bulk move of bugs I am assigned to from Milestone 5.2M4 to 5.3M1.