search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.19k stars 2.03k forks source link

Latex: too big margin around .. note role #9926

Open marxin opened 2 years ago

marxin commented 2 years ago

Describe the bug

Consider:

Code block:

.. code-block::

  gcc a.c
  ./a.out

And then there's a note:

.. note::

   I am a note!

And then there's something else.

I think the margin around note is quite big. What about making it smaller?

Screenshot from 2021-12-02 11-19-51

How to Reproduce

Build the snippet.

Expected behavior

No response

Your project

Build the snippet

Screenshots

No response

OS

Linux

Python version

3.8

Sphinx version

4.3.0

Sphinx extensions

No response

Extra tools

No response

Additional context

No response

marxin commented 2 years ago

And it's even bigger what note follows an .. option:: directive:

Screenshot from 2021-12-02 11-21-12

jakobandersen commented 2 years ago

I guess this would be theme-dependent. Which one are you using?

jakobandersen commented 2 years ago

I guess this would be theme-dependent. Which one are you using?

Doh, didn't see "Latex" in the title.

marxin commented 2 years ago

Doh, didn't see "Latex" in the title.

Yes, it's Latex :)

marxin commented 2 years ago

@jfbu Can you help us with that, please?

jfbu commented 2 years ago

About the extra spacing when the note is first thing in an option description I noticed there is some strange code in Sphinx latex writer: https://github.com/sphinx-doc/sphinx/blob/edd14783f3cc6222066fd63efbe28c2728617e18/sphinx/writers/latex.py#L759-L763

The ~ which ends up in LaTeX appears to be the culprit. I will have to check what motivated its insertion (this old legacy code is at least "14 years ago" https://github.com/sphinx-doc/sphinx/blame/c0ef6a92656cbada6702d0102b19d58c881763ed/sphinx/writers/latex.py#L816-L817).

This being said the note is rendered in LaTeX via the sphinxlightbox environment which does not really have hooks: https://github.com/sphinx-doc/sphinx/blob/3ae124f8ac038a3ca79aa266d4558fd85c6e6032/sphinx/texinputs/sphinxlatexadmonitions.sty#L34-L57

The spacing it creates is more or less the expected one for "display-block" objects, using only \par. Code-blocks on the other hand have a caption, and the associated vertical spacing has more-or-less being made comparable to tables. (iirc)

It is possible to \renewenvironment sphinxlightbox to insert custom vertical space handling (LaTeX knowledgeable users)

jfbu commented 2 years ago

Code-blocks on the other hand have a caption, and the associated vertical spacing has more-or-less being made comparable to tables. (iirc)

Code-blocks do not necessarily have a caption. The reduced vertical spacing compared to notes is a legacy situation. Notes and code-blocks share no common code for vertical spacing. There is a public parameter \sphinxverbatimsmallskipamount which can be modified in the preamble with \setlength and allows to adjust vertical spacing before code-block (default: \smallskipamount)., but there is no such public parameter for spacing after code-blocks.

Maybe we should add some such customizable spacings. It is an annoying fact of LaTeX that traditionally its verbatim environments (and this is inherited by Sphinx) use a so-called "trivlist". But affecting list parameters will impact all real list: itemized, enumerated, too. So we can not so much rely on official LaTeX layout parameters.

jfbu commented 2 years ago

There is a public parameter \sphinxverbatimsmallskipamount which can be modified in the preamble with \setlength

Sorry. Obviously I am a bit rusty. This \sphinxverbatimsmallskipamount is to be defined via \renewcommand, it is not a "LaTeX length variable".