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