sphinx-doc/sphinx

Text builder can't handle all tables

Open

#12,273 opened on Apr 12, 2024

View on GitHub
 (1 comment) (0 reactions) (0 assignees)Python (5,625 stars) (1,985 forks)batch import
builder:texthelp wantedtype:bug

Description

Describe the bug

It seems like the text builder can't handle all of the same tables that the html builder can. It is apparently possible for Table.colwidth elements to have a string value of 'auto', but Table.cell_width() assumes integer values.

...
  File ".../docutils/nodes.py", line 199, in walkabout
    visitor.dispatch_departure(self)
  File ".../sphinx/util/docutils.py", line 599, in dispatch_departure
    method(node)
  File ".../sphinx/writers/text.py", line 903, in depart_table
    self.add_text(str(self.table))
                  ^^^^^^^^^^^^^^^
  File ".../sphinx/writers/text.py", line 202, in __str__
    self.rewrap()
  File ".../sphinx/writers/text.py", line 181, in rewrap
    cell.wrap(width=self.cell_width(cell, self.colwidth))
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File ".../sphinx/writers/text.py", line 163, in cell_width
    width += source[cell.col + i]
TypeError: unsupported operand type(s) for +=: 'int' and 'str'

The problem occurs with a table provided through the Breathe extension, but the html builder handles it just fine.

How to Reproduce

I'm sorry for the complexity of the example. I don't know what determines whether a table node has column widths that are integers versus 'auto'. In pure RsT parts of my doctree, a Table produces Table.colwidth == [50, 50]. For the table that comes through Breathe, I see Table.colwidth = ['auto', 'auto'], which builds fine for the html builder, but can't be processed by the text builder.

  1. Create a doxygen comment block with a table using syntax like the following.
 *
 * colA    | colB
 * -------   | -------
 * term1     | definition1
 * term2    | definition2
  1. Produce Doxygen XML. Process with Breathe with a call like sphinx-build -b text . output/text

Environment Information

Platform:              darwin; (macOS-14.4.1-arm64-arm-64bit)
Python version:        3.11.7 (main, Dec  4 2023, 18:10:11) [Clang 15.0.0 (clang-1500.1.0.2.5)])
Python implementation: CPython
Sphinx version:        7.2.6
Docutils version:      0.20.1
Jinja2 version:        3.1.3
Pygments version:      2.17.2

Sphinx extensions

notably: breathe (4.35.0)

Additional context

The content that is being processed when the error occurs is extracted by breathe (4.35.0) from XML produced by Doxygen 1.10.0.

Contributor guide

Tech stack
python
Domain
documentation
Issue type
bug
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
half day
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
PythonSphinx writer architecture
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
60
Research direction
The fix should be in sphinx/writers/text.py, specifically in the cell width method (line 163). The method currently assumes all values in colwidth are integers, but they can be strings like 'auto'. The HTML builder likely handles this elsewhere. The contributor should check how docutils handles 'auto' column widths and ensure the text builder treats 'auto' appropriately (e.g., by ignoring or using a default width). See also the linked Breathe extension interaction.
Text builder can't handle all tables · sphinx-doc/sphinx#12273 | Good First Issue