Broken reference to label in included file (PDF output)

[afiaux]

Problem

Labels in files included using .. include:: file.rst cannot be referenced from the parent document, nor from other included files.

The references are displayed as the name of the label in the PDF output instead of a clickable link with the name of the section. The problem is present with :ref: and :numref:.

The problem is not present in the HTML output where the references are correctly replaced by clickable links with the section name.

Procedure to reproduce the problem

See reproducible project section.

Error logs / results

make latexpdf generates the following warning but this warning is also present when generating the HTML output which correctly works so it's probably not the cause of the bug.

subsec1.rst:4: WARNING: duplicate label probref, other instance in /tmp/include-ref-bug/subsec1.rst
/tmp/include-ref-bug/subsec1.rst:4: WARNING: duplicate label probref, other instance in /tmp/include-ref-bug/section1.rst

Expected results

The references should be replaced by clickable links with the name of the target section in the PDF output. Exactly like it is the case in the HTML output.

Reproducible project

Minimal project: include-ref-bug.tar.gz
Resulting PDF: include-ref-bug.pdf

Environment info

• OS: Arch Linux
• Python version: 3.6.0
• Sphinx version: 1.5.2
• pdfTeX: pdfTeX 3.14159265-2.6-1.40.17 (TeX Live 2016/Arch Linux)

Thank you in advance for your help.

[jfbu]

You should use toctree directive like this (this is section1.rst file)

Section 1
=========

Labels in sub-toctree files can be referenced.

.. toctree::
  
   subsec1
   subsec2

Subsection 3
------------

References also do work from parent document: :ref:`probref`

and the subsec1.rst file

.. _probref:

Subsection 1
------------

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt
ut labore et dolore magna aliquyam erat, sed diam voluptua.

Is there some special reason why you use include ?

[jfbu]

ah sorry I see HTML and LaTeX builder diverge here in behaviour. What I said is ok for LaTeX as the toctree inclusion is done by explicit file inclusion. For HTML it creates a local TOC which is not equivalent to what you try to achieve with include. I am too focused on LaTeX...

[afiaux]

Hi, thanks a lot for your quick response.

The reason I'm using .. include:: instead of .. toctree:: is that I have a huge appendix (hundred of pages) that I need to split among several files. And unfortunately .. toctree:: does not work in the LaTeX appendices (latex_appendices in conf.py).

If toctree:: is supposed to work in appendices, I can open another bug as this would also fix my problem if I no longer need to .. include:: files.

[jfbu]

if I understand correctly section1.rst in fact was trying to include different portions of what is destined to be a single appendix in latex PDF output. In that case you could try following mark-up:

.. raw:: latex

   \appendix

Appendix
========

Labels in sub-toctree files can be referenced.

.. toctree::

   subsec1
   subsec2

Subsection 3
------------

References also do work from parent document: :ref:`probref`

but do not use latex_appendices. From brief look at LaTeX builder code, I also get impression toctree (by design) does not work there. I tested make latexpdf and make singlehtml they give similar outputs, make html is different because it does not include the linked to documents, naturally, but shows a TOC.

[afiaux]

Thanks a lot, the raw:: latex solution fixed my problem. I can now have appendices split among several files with working references.

So if you consider that this is the way that appendices should be used and not with latex_appendices, feel free to close this bug.

Thank you again for your help!

[jfbu]

Keeping this opened awaiting enlightenment by experts ;-)

1. I am not sure about aim of latex_appendices, documentation is lacking. I observe they do work well with :ref: role. But each appendix file has to be marked :orphan: else a warning is emitted. Perhaps they should not generate these warnings as they are declared explicitely in latex_appendices.

2. Your main issue was about splitting one appendix into multiple subfiles. Maybe latex_appendices could allow items being themselves lists...

3. Your derived issue was about lack of cross-ref with .. included files. Perhaps this is something that should be better documented (I have not looked closely at docs); cross refs does not work with included files. (as far as I know, as I did not really check). (edit: in fact as include is pure docutils directive it is perhaps not surprising Sphinx :ref: 's does not work with it, but the doc here and here could be more explicit)

Thanks for reporting !

[tk0miya]

It seems the included docs are processed twice. So you'd seen the "duplicate label" warnings.

1. As a part of section1.rst. Sphinx considers included docs (subsec1.rst and subsec2.rst) as part of parent document. So probref label is defined at section1.
2. On the other hand, Sphinx searches the files named *.rst. As a result, subsec2.rst is processed as the document. This causes the problem. The probref label is also defined at subsec2.

Though the build process, Sphinx has been confused because the label has been appeared twice.
As a result, you got the broken conversion.

Tips: you should use other extensions for included documents (cf .txt).

[jfbu]

+1 @tk0miya. So it seems the correct procedure in the context of latex_appendices would be something like this

:orphan:

First appendix
==============

:index:`Labels` in files can be referenced.

.. include:: subsec1.rst.txt

.. include:: subsec2.rst.txt

Subsection 3
------------

References also do work from parent document: :ref:`probref`

for a file appendice1.rst which is listed in latex_appendices. But I needed to add :orphan: else there is a warning, and if this file is named appendice1.rst.txt there is an error.

But this latex_appendices means Appendix files are destined purely for LaTeX output and not other targets, which is strange.

[tk0miya]

It seems not a bug of Sphinx. So I close this now.
Thanks,