- Sponsor
-
Notifications
You must be signed in to change notification settings - Fork 2.3k
Open
Labels
Milestone
Description
Describe the bug
I used :width: 10%
in a table cell and got unsatisfactory results.

How to Reproduce
===================
FOO documentation
===================
image in table cell using width at 10%
======================================
+----------------------------+
| |
| .. image:: img.png |
| :width: 10% |
| |
+----------------------------+
+---+------------------------+
| a | b |
+---+------------------------+
| c | .. image:: img.png |
| | :width: 10% |
| | |
+---+------------------------+
+---+------------------------+
| a | b |
+---+------------------------+
| .. image:: img.png |
| :width: 10% |
| |
+---+------------------------+
Environment Information
Platform: darwin;
Python version: 3.13.3 (v3.13.3:6280bb54784, Apr 8 2025, 10:47:54) [Clang 15.0.0 (clang-1500.3.9.4)])
Python implementation: CPython
Sphinx version: 8.3.0+/e1bd9cb38
Docutils version: 0.21.2
Jinja2 version: 3.1.6
Pygments version: 2.19.1
Sphinx extensions
Additional context
Sphinx translates the 10%
into 0.100\linewidth
. But \linewidth
may be zero at some times of processing of tables 1. In the first two cases tabulary
fell back to its minium width of 10pt
. In the third case (merged cell), Sphinx emitted a varwidth
environment wrapper and seemingly \linewidth
had a normal interpretation.
Footnotes
-
it looks as I was going through a state of confusion here. It is not exactly clear what
\linewidth
is especially whentabulary
tries to find dynamically the best choice of column width, but it is not set to zero. Apologies. ↩
Metadata
Metadata
Assignees
Labels
Projects
Milestone
Relationships
Development
Select code repository
Activity
jfbu commentedon Jun 13, 2025
Here is what happens if we use
\textwidth
, not\linewidth
:The fact that the merged cell occupies full width and that the image is aligned left is due to other things (to start with, merged columns hard-code currently left alignment for legacy reasons, a PR should be done).
gmilde commentedon Jun 14, 2025
The problem is due to using a percentage value for the only non-empty elemnt in an "auto-width" column:
Determining the column width from the content while the content width depends on the column width is impossible. The different backends (HTML browser, LaTeX with code by the Docutils writer, LaTeX with code from the Sphinx writer) use different fallback methods with different results.
A possible fix in the writer would be to detect the situation, resist the temptation to guess, and report a warning.
Basing percentage values on the document-wide
\textwidth
would be problematic with valid use cases likeThe LaTeX output is sub-optimal. Try the HTML output in Docutils or Sphinx.
jfbu commentedon Jun 14, 2025
Thanks for feedback. Postponing this to 9.x milestone.
jfbu commentedon Jun 14, 2025
For the record here is with an added
where the file python-logo.png is found at https://github.com/sphinx-doc/sphinx/tree/master/doc/_static and the other used file is the
sphinx.png
at that location.HTML:
LaTeX->PDF:
I initially thought only LaTeX would display a small image, but this is not quite the case. So I less feel a sense of urgency here. Why does the python-logo ends up occupying more space in HTML? it may be related to its native dimension being larger. (1920 vs 200 pixels for sphinx.png)
jfbu commentedon Jun 14, 2025
To be completely honest here, I tried out this example and made a number of comments on the premise that
\linewidth
is a strange beast in table cells (which is not wrong, in view of some manipulations related to it in dark corners ofsphinxlatextables.sty
which I have rediscovered now), even possible zero, but in fact I may have made here a confusion with\baselineskip
which is set to zero in table cells of thel
,r
, orc
types. I will try now to locate my comments of recent times and maybe correct them.gmilde commentedon Jun 14, 2025
A collection of different samples with images in tables. Works in Sphinx and Docutils but the output differs (and is sub-optiomal in different ways.
gmilde commentedon Jun 14, 2025
The column width of this table is determined by its content.
The width of the content should be 10% of the column width.
What result would you expect???
gmilde commentedon Jun 14, 2025
While I don't know of any way to get the height of a containing element,
\linewidth
is (in most cases) a suitable dimension for the currently available width.gmilde commentedon Jun 14, 2025
I use the "evince" PDF viewer, that offers a drop down list for the magnification with "adapt to page", "adapt to width", "auto", "5o%", 70%, ... , 400%.
"adapt to width" fits the paper-width into the viewport. I don't know how to automatically set the magnification to show the text block.
jfbu commentedon Jun 14, 2025
I expect
10%
of the width of where the table is going to stand. So10%
of text area width. In this manner the10%
means the same things in all cells, even merged ones of the table.I will remain cautious about what I will say about
\linewidth
, due to my recent blunders, but, as Sphinx uses for short tables without problematic elementstabulary
, it is not all clear what\linewidth
will end up being and may differ between first and second pass of tabulary. Also, merged cells use avarwidth
environment, so here again it is not at all clear what\linewidth
will end up being. I think what most users would (no, should, I am very prejudiced here so "most users" is synonymous with "me") expect that\linewidth
refers to the width of the immediate parent of the table, so the\textwidth
if at top level. Or the reduced value if in a list or quoted blocks (I progress towards rejoining your view on nested lists).I understand it could make sense to ask for an image to occupy "half" the width of the cell, if the cell contains some other contents deciding of that width, but in my view, this is really a fringe case.
A weak point of my intuitive interpretation of what
%
should mean there is that, basically I feel that as the LaTeX output size can not change, something like%
makes sense only if having as comparison something absolute, so in effect I am advocating that for PDF output%
should have some aspect of absoluteness and all cells of a table independently of their width should interpret%
the same.But don't think I am pushing this too much: nobody ever complained so far so I am anticipating it will not be worthwile to change anything.
I confirm what you say, and apologize, but uninteresting details are relegated to a foonote 1.
Footnotes
I am using Skim on macOS but I recently upgraded my hardware and could not on my current hardware re-confirm certain memory impressions which I thought solid for more than a decade. As it stands I do not even find "Fit to width" anymore, only some "Adapter à l'écran" in French which is non-sense because the original was probably "Adapt to window", "écran" meaning "screen" i.e. the total size of my device, and anyhow what it does is as for you to fit paperwidth inside the (unmodified) window, contrarily to what I recalled of "Fit to width". I do not find anywhere in the Skim menubar some "50%" etc... scaling as I was used to see, they have disappeared, the closest I find is via CTRL-click with a pop-up showing options such as "Zoom-in" "Zoom-out" (in French) and I can also do
CMD-+
orCMD--
. ↩jfbu commentedon Jun 14, 2025
It appears all examples at
100%
do work out reasonable in PDF via Sphinx in the sense that the image does occupy100%
of the cell it occupies. The:width: 3 3
gets interpreted as having columns with same width, it is rendered in LaTeX with\begin{tabular}[t]{\X{3}{6}\X{3}{6}}
whereX{a}{b}
witha
andb
integers assigns (taking into account the tabcolsep)a/b
of the total available width, here is the textwidth. The "grid" case renders via\begin{tabular}[t]{\X{1}{28}\X{27}{28}}
. The:width: 50%
seems to be ignored altogether I don't know off-hand what that:width: 50%
is supposed to mean. The rendering uses\begin{tabulary}{\linewidth}[t]{TT}
.jfbu commentedon Jun 14, 2025
For the examples you provided you can control the looks in the PDF via the conf.py variable
latex_table_style
. The current default value is['booktabs', 'colorrows']
, and to recover about the same as what had been until some years ago the longtime legacy rendering one should saylatex_table_style = ['standard', 'nocolorrows']
. Or now that I check, simply['standard']
. Or rather simplylatex_table_style = []
.gmilde commentedon Jun 17, 2025
This is one of several possible valid assumptions.
As a consequence, a width of
100%
would always overflow in a table(similar to
100vw
in any normal text).IMO, setting the width of an element to a percentage of available space is not more "exotic" than setting its width to a percentage of the global text width.
The width of a table cell can also be specified in the rST source as combination of the
:width:
and:widths:
options for the "table", "csv-table" or "list-table" directives. (The "width" of a table seems to be currently ignored by Sphinx-LaTeX but this is a separate issue.)IMV, the use case that I want an object (table, image, or figure) to be centre-aligned and take 75% of the width of the current text block (be it a paragraph, a quote, a list item or a table cell) is quite common. This is why the CSS standard "invented" the percentage values for sizes.
If 75% in a LaTeX table became 0.75*textwidth we would end up with a lot of inconsistencies. The interpretation in HTML will not change, so the inconsistency would be either between output formats (and Docutils vs. Sphinx) or between tables (may be only auto-width tables) and all other elements that may contain a table, figure, or image.