Prefer existing label to generate HTML node ID when possible

[sehmaschine]

The HTML which is produced with labels before section is quite arbitrary. It sometimes works, but most of the time it doesn't.

Here's an example:

.. _attachments-fields:

Felder
++++++

This should lead to:

<div class="section" id="attachments-fields">
    <span id="id2"></span>
    <h3>Felder
        <a class="headerlink" href="#attachments-fields" title="Permalink to this headline">¶</a>
    </h3>

But it actually produces this:

<div class="section" id="felder">
    <span id="attachments-fields"></span>
    <h3>Felder
        <a class="headerlink" href="#felder" title="Permalink to this headline">¶</a>
    </h3>

[birkenfeld]

I guess it is a little random which of the several IDs gets assigned as "id", and which is used as supplementary "id"s.

Is there a concrete problem with this behavior?

[shimizukawa]

Sphinx (docutils) uses label as a id preferentially if the label is provided.
In that sense, it's stable I think.

[sehmaschine]

@shimizukawa When you look at the example above, I think it's not quite true that the label is being used. That's exactly the problem.
@birkenfeld The main problem is that it's hard to reference the anchor. Sometimes it's the label, sometimes the section ID. It's completely arbitrary.

[shimizukawa]

@sehmaschine you are right. I retract my word.

I tried rst2html docutils command and it generates same output.
In my investigation, it seems that it's a specification of docutils. docutils uses such label as a reference target instead of implicit target. OTOH, docutils marks section title as a implicit target.

IMO, we shouldn't change the rule from sphinx side.

memo:

http://repo.or.cz/w/docutils.git/blob/HEAD:/docutils/docutils/parsers/rst/states.py#l389

 375     def new_subsection(self, title, lineno, messages):
 ...
 389         self.document.note_implicit_target(section_node, section_node)

note_implicit_target makes id from section title

http://repo.or.cz/w/docutils.git/blob/HEAD:/docutils/docutils/parsers/rst/states.py#l1923

1917     def make_target(self, block, block_text, lineno, target_name):
...
1923             self.document.note_indirect_target(target)

make_target is called from hyperlink_target (=label).

[kkzhang]

I stil think it is a bug.
I cann't explict set label name under some condition, it's rediculous. In my case, i want to generate a page for FAQ, which is full of Q&A, each of it should have a anchor to be referenced.

[tk0miya]

It seems you can refer the anchor point with #attachments-fields URI-fragment. Do you mind about the URI-fragment of permalink <a class="headerlink" href="#felder" title="Permalink to this headline">¶</a>?

Internally, section titles can have multiple node IDs. The first one is generated from its title ("Felder" -> felder). Remainings come from the user-defined labels. The HTML writer of Sphinx generates the permalink from the first one of the section title.

I understand you'd like to use an user-defined label to its permalink. But I wonder how we should do when users gives multiple labels to the section title:

.. _foo:
.. _bar:
.. _baz:

folder
++++++

So I vote -1 for changing this behavior.

[mhsmith]

For internal links within my documentation, I can link to a section using :ref:, as recommended in Sphinx's own documentation:

Using ref is advised over standard reStructuredText links to sections (like `Section title`_) because it works [...] when section headings are changed

But if someone copies the "permalink" from the section header, that link will break as soon as I reword the header. On an FAQ page with one section per question, that might happen quite often. Apparently the "permalink" isn't so permanent after all.

If I'm the one sharing the link, then I can work around this by sharing a link to the hidden label anchor, even if I have to look in the HTML or RST source to find it. But what about my users sharing links with each other?

I understand you'd like to use an user-defined label to its permalink. But I wonder how we should do when users gives multiple labels to the section title:

In that case, all the labels are at the same point in the document, so they're functionally equivalent, and all of them are more permanent than the section title. Would there be any downside to Sphinx just using the first one?

As well as the "permalink" links in the section headers, this would also apply to section links from tables of contents and sidebars.

[GeeTransit]

For anyone stumbling on this issue, I created a Sphinx extension that checks for targets preceding section headers and uses them as the section ID.

With this input:

.. _attachments-fields:

Felder
++++++

The following HTML is produced:

<section id="attachments-fields">
    <span id="felder"></span>
    <h3>Felder
        <a class="headerlink" href="#attachments-fields"
            title="Permalink to this headline">
            ¶
        </a>
    </h3>
</section>

The permalink is the one manually specified (#attachment-fields), not the one generated from the title (#felder).

When multiple targets exists, the last one is used (easier to remember + simpler implementation).

This change is backward compatible too. :ref:`attachments-fields` points to the section header and so does Felder_. Old permalinks also work (because the #felder element still exists). If the section ID happens to be id2 or similar, it'll still have id2 because the extension reorders the section's IDs after they're generated.

Extension: https://github.com/GeeTransit/sphinx-better-subsection
See it in action: https://geetransit.github.io/sphinx-better-subsection/_generated/CHANGELOG/

[mhsmith]

@GeeTransit Thanks, this is great! But still think this should be fixed in Sphinx itself.

[GeeTransit]

I also agree that Sphinx should use the target for the permalink. It's a bit weird that :ref:`attachment-fields` is more permanent than the permalink. For now, I'm fine with using an extension to patch this behaviour.

I'm happy to create a pull request that adds the extension's PreferSectionTarget transformer into sphinx/transforms/__init__.py though.