10000 DOC: a LaTeX hack from conf.py gives extra whitespace in PDF with Sphinx 5 · Issue #22941 · numpy/numpy · GitHub
[go: up one dir, main page]
Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
jfbu opened this issue Jan 5, 2023 · 0 comments · Fixed by #22952
Closed

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

jfbu opened this issue Jan 5, 2023 · 0 comments · Fixed by #22952
Labels
04 - Documentation

Comments

@jfbu
Copy link
Contributor
jfbu commented Jan 5, 2023 •
edited
Loading

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 ;-)
jfbu added a commit to jfbu/numpy that referenced this issue Jan 5, 2023
@jfbu
DOC: remove old LaTeX hack if Sphinx is at 5.0.0 or later (fix numpy#…
e917cb6 
…22941)
jfbu added a commit to jfbu/numpy that referenced this issue Jan 5, 2023
@jfbu
DOC: remove old LaTeX hack if Sphinx is at 5.0.0 or later (fix numpy#…
7cf5500 
…22941)
@jfbu jfbu mentioned this issue Jan 5, 2023
Merged
seberg pushed a commit that referenced this issue Jan 6, 2023
@jfbu
DOC: remove old LaTeX hack if Sphinx is at 5.0.0 or later (fix #22941) (
890920e 
#22952)

This removes an old LaTeX hack if Sphinx is at 5.0.0+. The hack served to insert a newline after each parameter name before its description and is unneeded as Sphinx 5+ does it (otherwise) and it now causes extra vertical whitespace.

If one day in future NumPy pins Sphinx to be at least 5.0.0, the whole thing will become removable.

Closes #22941

EDIT: this also removes \usepackage{xcolor}. Sphinx for many many years uses xcolor if it is available.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
04 - Documentation
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

DOC: remove old LaTeX hack if Sphinx is at 5.0.0 or later (fix #22941) jfbu/numpy
1 participant
@jfbu
0