sphinx-doc / sphinx-doc/sphinx
Including rst in toctree multiple times not possible with latex builder
Nobody has claimed this yet.
- 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
Environment info
- OS: Windows 10
- Python version: Python 2.7.15
- Sphinx version: Sphinx (sphinx-build) 1.6.5
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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