Sphinx: Latex produces empty pages after title and table of contents

[nmat]

Reported before. Empty pages are created using miktex and latexpdf during make process.

Even if make goes through.

[jfbu]

is it possible you try to present minimal rst source creating the problem ?

[nmat]

@jfbu sorry I am not following?

[jfbu]

@nmat perhaps I missed something from your original report, I will check. But I can not reproduce your problem without appropriate source which I can use. (assuming this is not a MikTeX issue).

[nmat]

This could be only miktex related. I am not 100% sure. Should I try to build it on linux also?

[jfbu]

as far as I know MikTeX is very much alike TeXLIve, in so far as packages are fetched from CTAN. It is very rare a problem is only with MikTeX. I am quite confident all packages used by Sphinx for LaTeX are the same on MikTeX and TeXLive, if both are up-to-date. It would be useful if you can reduce the problematic document to a minimal project. Because apart from concluding that pdflatex compilation presumably ended in error, I can't say anything from the fact that there are blank pages in output.

[nmat]

I can make it simple really.

1. Created a new directory
2. Ran the quickstart (standard settings) no changes in conf.py
3. In index.rst I added

testing/index.rst

1. In testing/index.rst I added a simple header and paragraph

Ran the latexpdf and boom several pages of empty information.

NOTE also that I use 2 spaces for indenting in the rst files.

Build output: https://gist.github.com/nmat/273a28fbb3a406840da3d7c2c98ed84e

System information:
Sphinx: 1.4.3
Python: 3

[jfbu]

I did reproduce your issue following your instructions.

Remove in index.rst the line above .. toctree:: containing the word Contents:.

I never observed it because I have not used for a long time the quickstart script. I always copy an earlier project skeleton. Instead.

Does this fix it for you ?

[nmat]

It did fix the content header page not generated as blank.....but there are still other pages that are blank. :/

[jfbu]

With

latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     #
     # 'papersize': 'letterpaper',

     # The font size ('10pt', '11pt' or '12pt').
     #
     # 'pointsize': '10pt',

     # Additional stuff for the LaTeX preamble.
     #
     # 'preamble': '',

     # Latex figure (float) alignment
     #
     # 'figure_align': 'htbp',
    'extraclassoptions': 'openany',
}

you get rid of blank pages needed by default for manual, which is that chapters open on odd pages.

I observe only one blank page after first one of table of contents.

This is no bug I think, but probably standard behaviour of report LaTeX class.

Perhaps howto in latex_documents in conf.py is more suited to your needs ?

[jfbu]

ah ok I see some code including

    \cleardoublepage%

after table of contents in sphinxmanual.cls. It is late here, I will investigate another time the code above which looks strange, because \cleardoublepage should do the job by itself.

[nmat]

makes sense. Yeah I tested it. And still get 1 blank page after header and one after contents.

So it did remove a lot but still kept a few blank pages. Late here also. so will continue tomorrow.

If you want to talk directly to me then I am on IRC also.

[jfbu]

seems like sphinxmanual.cls does not obey openany option for first chapter after table of contents, hence you possibly found a Sphinx bug. I will investigate tomorrow.

[jfbu]

I have possibly fixed it, can you test PR #2626 ?

• you must use 'extraclassoptions': 'openany', in latex_elements,
• to avoid the issue with the Contents: line in index.rst, you should set sixth element of latex_documents to True:

latex_documents = [
    (master_doc, 'testnmat.tex', 'testnmat Documentation',
     'jfbu', 'manual', True),
]

This way you can still have Contents: in html output.

@tk0miya shouldn't default value of sixth element to latex_documents be True? the Contents: line in index.rst from quickstart script is very bad for LaTeX.

[nmat]

Verified and works here.

Both solutions fixes blank pages and also the extra content while still keeping html content.

Nicely done!

[jfbu]

@nmat good to know, thanks.

[nmat]

Should I close the ticket?

[jfbu]

@nmat keep it open please until PR is reviewed and perhaps merged. I have modified it substantially, does latest version still work for you ?

[nmat]

Yes the latest version works just fine.

[nmat]

Will keep it open until it is commited and pushed. Nice work @jfbu

[jfbu]

Thanks @nmat for patience in explaining the problem and checking proposed fixes 👍

[nmat]

You are most welcome! I will try to help as much as I can with testing.

[tk0miya]

@jfbu I think the sixth element of latex_documents a.k.a toctree_only is too complicated for users.
It ignores all contents in the startdoc. Then users should write contents to except startdocs.

So it is not good for me to enable it by default

[jfbu]

@tk0miya yes I understand. If quickstart script wrote something (put here some optional contents) rather than Contents: it would be more obvious to users when they do make latexpdf the first time why they get something funny after table of contents. When one sees a blank page with "Contents:" one may take time to understand it comes from index.rst.

I think when I first started with Sphinx I followed examples were index.rst was only for toctree and one must use other files. Only later when starting experimenting with issues reported here did I understand I could put material directly in index.rst. Thus it seems you think new users have the opposite idea to the initial mine and they will use only index.rst by default ;-)