LaTeX writer: Make it possible *not* to automatically label enumerable nodes

[paternal]

Subject: When a custom extension defines an enumerable node, the LaTeX writer labels it, whether the extension author wants it or not. This leads to duplicate labels, or bogus numbering.

Problem

The problem arises in the following lines.

https://github.com/sphinx-doc/sphinx/blob/a4cce3e5613b4c721c19426fc120bbeeb830c3b2/sphinx/writers/latex.py#L1820-L1824

If the next node does not have a title, a label is created, before the node. But it may be interesting to have a label inside the node. For instance, in stuffcounter (a dummy extension to illustrate/play with enumerable nodes), in LaTeX, enumerable nodes are rendered as LaTeX environment (theorems here, but this is irrelevant). Thus, the generated code looks like:

\label{some-label}
\begin{stuff}
   Some stuff.
\end{stuff}

The problem is that the label being outside the environment, it is not numbered correctly (it bears the number of the previous environment). What I would like is:

\begin{stuff}
   \label{some-label}
   Some stuff.
\end{stuff}

With named nodes, no automatic label is placed, and I achieve this by setting the label myself (using hypertarget_to()). With unnamed nodes, however, an automatic label is placed. There are two possibilities:

• I place another label, but I get a LaTeX warning: Label `index:some-label' multiply defined.
• I do not place another label, but the number of references is wrong (reference number is incremented when entering the environment, which is not done before the environment).

Procedure to reproduce the problem

See sphinx-contrib/stuffcounter#1.

The caption (title) is defined here:

https://github.com/sphinx-contrib/stuffcounter/blob/cbf1fecaf9fc62c2d6e0c31c7d753aad4f618e35/sphinxcontrib/stuffcounter/__init__.py#L33-L46

The label is placed there:

https://github.com/sphinx-contrib/stuffcounter/blob/cbf1fecaf9fc62c2d6e0c31c7d753aad4f618e35/sphinxcontrib/stuffcounter/__init__.py#L137-L141

Expected results

I see two ways to solve this:

• never add a label for enumerable nodes, even ones without a title (but this might break things);
• provide a way (for extension authors) to say "even though this enumerable node has no title, I do not want an automatic label".

Environment info

• OS: Linux (Debian testing)
• Python version: 3.6
• Sphinx version: branch 1.8

Proposal

I can submit a patch, but I need pointers to your preferred solution: I could add an attribute do_not_add_latex_label to enumerable nodes, I could add an attributes enumerable_nodes_that_are_not_to_be_automatically_labelled, etc. I cannot imaging a perfect solution, so I would like to here your favourite one before starting to implement it.

[jfbu]

Sorry for delay, this is very legitimate query.

@tk0miya I have looked very superficially and I am not good yet at how Sphinx handles references, but it appears HYPERLINK_SUPPORT_NODES in https://github.com/sphinx-doc/sphinx/blob/38c5ec13a54a2b7fcd7e70956ee99a656a651f13/sphinx/builders/latex/nodes.py#L40-L46 is designed to hold the nodes which on LaTeX side somehow manage their own \label placement. Is there a way to open this to extensions?

[tk0miya]

At present, enumerable nodes are designed that all enumerable nodes have title. So you need to give title_getter to app.add_enumerable_node(). If the expectation is not good for your case, let's improve our implementation. I know current implementation is not perfect. https://www.sphinx-doc.org/ja/master/extdev/appapi.html#sphinx.application.Sphinx.add_enumerable_node

[paternal]

Two questions:

1. What is the difference between a title and a caption? I would guess that:

   • a caption is the text explaining what the figure is (e.g. "Figure 1: Results of the experiment");
   • a title is used when referencing the node (e.g. "The raw results can be seen if figure 1 (results).")

   Am I wrong?

2. What if I want a node without a caption? For instance, if my nodes are math theorems (e.g. "Theorem 1", "Theorem 2"), some of them may not have captions (look for "Theorem" in this paper). Can I do this with an enumerable node?