Thanks to visit codestin.com
Credit goes to github.com

Skip to content

DOC: a LaTeX hack from conf.py gives extra whitespace in PDF with Sphinx 5 #22941

Closed
@jfbu

Description

@jfbu

Issue with current documentation:

In the conf.py there is LaTeX hack which is described as

% In the parameters section, place a newline after the Parameters
% header

It was modified by myself 3 years ago in #15028 to fix some bug in the very old LaTeX package used and address a compatibility with a change in Sphinx.

At Sphinx 5.0.0, there was some change so that basically the numpy style was adopted but with a different implementation upstream (sphinx-doc/sphinx#9999). It was checked this would not break numpy. Some other changes happened at Sphinx 5.1.0 (sphinx-doc/sphinx#10087) which may impact this. Perhaps already sphinx-doc/sphinx#8997 from Sphinx 4.0.0 is relevant.

Anyway, currently the hack from numpy seems to be superfluous and a bit detrimental, adding to my taste too much vertical whitespace:
Capture d’écran 2023-01-05 à 14 58 24

Here is output if removing this hack entirely from conf.py:
Capture d’écran 2023-01-05 à 14 56 14

Idea or request for content:

I would advise to remove the hack entirely if and when Sphinx will be pinned to >=5.0.0. I checked the above screenshots with or without the patch would be the same with Sphinx 5.0.0 as with the 6.1.0 they were produced with originally. I did not test with Sphinx 4.0.0 due to some problem with the Python 3.10.9 environment where I have currently installed numpy and scipy.

i.e. do

-% In the parameters section, place a newline after the Parameters
-% header
-\usepackage{xcolor}
-\usepackage{expdlist}
-\let\latexdescription=\description
-\def\description{\latexdescription{}{} \breaklabel}
-% but expdlist old LaTeX package requires fixes:
-% 1) remove extra space
-\usepackage{etoolbox}
-\makeatletter
-\patchcmd\@item{{\@breaklabel} }{{\@breaklabel}}{}{}
-\makeatother
-% 2) fix bug in expdlist's way of breaking the line after long item label
-\makeatletter
-\def\breaklabel{%
-    \def\@breaklabel{%
-        \leavevmode\par
-        % now a hack because Sphinx inserts \leavevmode after term node
-        \def\leavevmode{\def\leavevmode{\unhbox\voidb@x}}%
-    }%
-}
-\makeatother

The \usepackage{xcolor} can be removed although unrelated because Sphinx loads xcolor automatically if available (since many years).

Ah well about more than a year ago I commented at sphinx-doc/sphinx#9999 (comment)

As far as I tested briefly, this does not cause breakage if used with numpy's hack into LaTeX description lists, but the hack of their project should be removed entirely, as it causes bad extraneous vertical whitespace.

So actually I was aware of that but may have entirely forgotten to trigger the alarm here ;-)

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions