In singlehtml output, anchors are non-unique

[spwhitton]

We use make singlehtml to produce single page HTML documentation from multiple input files.

The output can be viewed here: https://www.debian.org/doc/debian-policy/

As you will see, HTML anchors are non-unique. For example, there are many footnotes which each have the anchor #id1. And several sections have the anchor #introduction. This means that is is not possible to create hyperlinks to particular sections of the document. And links to footnotes often point to the wrong place -- the browser takes you to a footnote with the same anchor in another section of the document.

We can work around the non-uniqueness of section anchors by manually specifying unique section IDs for each of our sections, but that does not help with the footnotes issue.

The source is here: https://salsa.debian.org/dbnpolicy/policy/tree/master/policy

Our bug reports: https://bugs.debian.org/879048 , https://bugs.debian.org/876075

Environment info

• OS: Debian unstable
• Python version: 2.7.14+
• Sphinx version: 1.6.7

Thanks!

[osamuaoki]

Since Sphinx is an extended Docutils and it can be further extended to change its build behavior. I suppose indexing for footnote, section, etc. are no different. So using tricks like below should enable to fix reported problems for singlehtml build by the document package ;-):

• http://docutils.sourceforge.net/docs/dev/hacking.html#extending-docutils
• https://www.sphinx-doc.org/en/master/extdev/index.html
• https://www.sphinx-doc.org/en/master/development/tutorials/index.html

One way for extension is overriding "nodes.py" by not resetting like:

• docutils/nodes.py: self.id_start = 1
• docutils/nodes.py: self.autofootnote_start = 1

for each document reading.

Another approach for extension is to modify "writers" to include chaper number in autogenerated id-string.

The latter approach should provide more robust URL links when document is updated, I think.

If anyone has such code, we can update shinx later.

As long as the pertinent extension is activated under

     if self.builder.name == 'singlehtml':

this is safe for future sphinx updates ... I guess.

(This is more for my reminder. This sphinx code is too complicated for me and I still need to lern extension etc..)

[dbetm]

I've created a simple Python script to de-duplicate the anchor id's in the generated single HTML file, the gist: https://gist.github.com/dbetm/8f0b8ca0b46e1efff3fa5f16ec7be9f1

[gastmaier]

Using a transformer works:

class unique_ids(SphinxTransform):
    """
    Suffix IDs/anchors to make them unique, e.g.
    {overview, features, ..., overview} ->
    {overview, features, ..., overview-1}
    """
    default_priority = 500
    used_ids = set()

    def apply(self, **kwargs: Any) -> None:
        if self.app.builder.name != "singlehtml":
            return

        def make_unique_id(node, id_):
            """
            A node contains multiple ids, the first is the title
            text converted to ID, then, if present, the label
            e.g.:
              .. _documentation+a label:

              My header
              ---------

            becomes:
              ["my-header", "documentation-a-label"]

            The first is the one is the one we worry about collision
            """
            counter = 1
            id__ = id_
            while id__ in self.used_ids:
                id__ = f"{id_}-{counter}"
                counter += 1
            self.used_ids.add(id__)
            node['ids'][0] = id__

        # findall (Docutils >= 0.18.1) returns an iterator,
        # and deprecates traverse (returns a list).
        # Sphinx 7.1.2 requires Docutils >= 0.18.1
        for node in self.document.findall():
            if (not isinstance(node, nodes.Text) and
                'ids' in node and node['ids']):
                make_unique_id(node, node['ids'][0])

#  ....
def setup(app):
     app.add_post_transform(wrap_elements)

By creating a "global" used_ids set, persistent between the transformer call per doc.

@Agadoul

[sbaillou]

Thanks for the code @gastmaier ! It helped a lot. :)

I tweaked it a bit so it runs in our flow and ended up with this. The critical change was using add_transform instead of add_post_transform.

from sphinx.transforms import SphinxTransform
from typing import Any
from docutils import nodes

class unique_ids(SphinxTransform):
    """
    Suffix IDs/anchors to make them unique, e.g.
    {overview, features, ..., overview} ->
    {overview, features, ..., overview-1}
    """
    default_priority = 500
    used_ids = set()

    def apply(self, **kwargs: Any) -> None:
        if self.app.builder.name != "singlehtml":
            return

        def make_unique_id(node, id_):
            """
            A node contains multiple ids, the first is the title
            text converted to ID, then, if present, the label
            e.g.:
              .. _documentation+a label:

              My header
              ---------

            becomes:
              ["my-header", "documentation-a-label"]

            The first is the one is the one we worry about collision
            """
            counter = 1
            id__ = id_
            while id__ in self.used_ids:
                id__ = f"{id_}-{counter}"
                counter += 1
            self.used_ids.add(id__)
            node['ids'][0] = id__

        # findall (Docutils >= 0.18.1) returns an iterator,
        # and deprecates traverse (returns a list).
        # Sphinx 7.1.2 requires Docutils >= 0.18.1
        for node in self.document.findall():
            if (not isinstance(node, nodes.Text) and
                'ids' in node and node['ids']):
                make_unique_id(node, node['ids'][0])

def setup(app):
    app.add_transform(unique_ids)