sphinx-doc / sphinx-doc/sphinx

Including rst in toctree multiple times not possible with latex builder

Open
#5,145 2 comments 4 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

internals:toctree markup
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

When including an .rst file multiple times by including it via toctree, the file is only rendered the first time when rendering it with the LaTeX builder. On the other hand multipage-html output seems to work fine.

Problem

We have a document which describes general configuration switches for multiple plugins by including the file containing these switches in multiple parts of the document via toctree. A simplified structure that demonstrates the problem is as follows:

index.rst:

Contents:

.. toctree::
   :maxdepth: 2

   test
   test

test.rst:

This is just a test
###################

With some text

When rendering the document with sphinx-build -b latex . _build\latex the file is only included the first time it is encountered, while, when using sphinx-build -b html . _build\html the document is generated as expected. We would expect the generated LaTeX file to contain the included section each time it is included.

It seems the problem is caused by the function sphinx.util.nodes.inline_all_toctrees, which recursively resolves toctrees. This function uses parameter traversed to avoid circular references, by omitting files that have already been processed as toctree entries. Unfortunately this not only solves this problem, but also prevents including files multiple times, even if this would not cause a circular reference. It seems, this behaviour has been introduced with issue 1540

Find attached a minimal example to reproduce the issue.

Reproducible project / your project

sphinx_test.zip

Environment info
  • OS: Windows 10
  • Python version: Python 2.7.15
  • Sphinx version: Sphinx (sphinx-build) 1.6.5

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with sphinx.util.nodes.inline_all_toctrees and the LaTeX builder, using the attached sphinx_test.zip minimal project to reproduce the difference between LaTeX and multipage HTML output. Trace how the traversed parameter suppresses repeated toctree entries, then verify that the generated LaTeX includes test.rst each time without breaking circular-reference protection.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.