A potential display bug with the LaTeX generation step in Sphinx

[schoi32]

Describe the bug
Sphinx-generated PDF file with an Index section having long lines overlapping each other

To Reproduce
Steps to reproduce the behavior:

<Paste your command-line here which cause the problem>

$ conda create --name qmcpy python=3.6
$ conda activate qmcpy
$ git clone https://github.com/QMCSoftware/QMCSoftware.git
$ cd QMCSoftware
$ git checkout develop
$ pip install -r requirements/dev.txt
$ pip install -e ./
$ make qrng
$ pip install -r requirements/dev_docs.txt
$ make doc_pdf

Expected behavior
Remove overlap or make one-column Index pages in the last few pages in the PDF (URL below)

Your project
https://readthedocs.org/projects/qmcpy/

Screenshots
Please see the last few pages of the PDF at https://qmcpy.readthedocs.io/_/downloads/en/develop/pdf

Environment info

• OS: Linux/Mac
• Python version: [e.g. 3.6]
• Sphinx version: <2
• Sphinx extensions: sphinx.ext.autodoc, recommonmark
• Extra tools: gcc, pdflatex

Additional context

• https://qmcpy.readthedocs.io/_/downloads/en/develop/pdf/

[tk0miya]

Screenshots:

[rscohn2]

You may be able to avoid this problem by making the index text smaller. See printindex in the docs: https://www.sphinx-doc.org/en/master/latex.html for directions. For especially long text, you may want to make your index single column. See printindex in this unmerged PR #8328

[schoi32]

Many thanks, Robert. I have worked in the fix to make the Index one column: QMCSoftware/QMCSoftware@061624a This is the associated PDF: https://qmcpy.readthedocs.io/_/downloads/en/develop/pdf/ <https://qmcpy.readthedocs.io/_/downloads/en/develop/pdf/> Sou-Cheng Choi Research Associate Professor Department of Applied Mathematics Illinois Institute of Technology, USA

…

On Oct 26, 2020, at 10:02 AM, Robert Cohn ***@***.***> wrote: You may be able to avoid this problem by making the index text smaller. See printindex in the docs: https://www.sphinx-doc.org/en/master/latex.html <https://www.sphinx-doc.org/en/master/latex.html> for directions. For especially long text, you may want to make your index single column. See printindex in this unmerged PR #8328 <#8328> — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#8055 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABKP626QRNTUPYGSWVRD7TDSMWFPNANCNFSM4PU2T6HA>.

[rscohn2]

Thanks for sharing. That is a better solution. I will use it.

[jfbu]

@tk0miya we already require package makeidx as used in linked approach from #8055 (comment)
but not package idxlayout. Perhaps we would add this to the documentation of latex_elements?

BTW, I don't understand that our docs says that 'makeindex' key is set by other options and should not be modified. I see nothing actually that changes it (be it on builder or writer side).

[tk0miya]

I'm thinking it's really worthy if we'll add a new configuration (for example, latex_index_page_style = 'onecolumn' | 'twocolumn'), and generate the LaTeX document using idxlayout automatically.

[jfbu]

Here is a no-package approach. It works with our standard 'manual' and 'howto' classes:

latex_elements = {
    'printindex': r'\def\twocolumn[#1]{#1}\printindex',
}

This is trick to workaround inflexible hardcoded definitions of theindex environment by vanilla standard classes of LaTeX (article, book). Not tested with Japanese classes.

As per idxlayout, it is probably good solution as it seems to know about memoir and KOMA classes. Not tested with Japanese. It requires etoolbox package (as well as multicol and ragged2e but those should be in any base latex distribution) which one would have to check if always in Linux distros.

@tk0miya I am tempted by simply extending our documentation of \printindex to indicate above possibility and the idxlayout approach, but not add configuration variable and not change anything to our default.