Tables: Support widths: auto and make it the default

[imphil]

Support the widths: auto option of table, csv-table and list-table directives, as specified in https://www.docutils.org/docs/ref/rst/directives.html.

Make the Typst writer use widths: auto by default, similar to the HTML5 or LaTeX writers, for cases where no widths option is given.

Summary by CodeRabbit

• Documentation

  • Expanded table examples with new autolayout and auto-width variants for list, CSV, simple, and grid tables.
  • Added additional truth-table examples showing both grid-derived and explicitly set widths.

• Bug Fixes

  • Updated table rendering so automatic column sizing is used by default when widths aren’t explicitly provided, while preserving fixed widths when they are.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: b3269890-ec77-490f-bfb4-5663508c0308

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

visit_tgroup in src/rst2typst/writer.py now chooses Typst table column output based on the parent table’s colwidths-given class. Several table spec snippets were updated: two existing examples now use auto sizing, two explicit-width examples were added, and new autolayout/auto-keyword list-table and csv-table examples were added and linked from docs/spec/tables/index.rst.

Estimated code review effort: 3 (Moderate) | ~20 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly captures the main change: adding support for widths: auto and making it the default for tables.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

src/rst2typst/writer.py (1)

542-554: ⚡ Quick win

Code clarity issue: confusing node-to-string comparison.

Line 549's condition if colwidths_given and colspec != "auto": is semantically confusing. The variable colspec is a nodes.colspec object, not a string, so the comparison colspec != "auto" will always evaluate to True. This makes the condition effectively identical to if colwidths_given:, rendering the second part redundant and unclear to readers.

The logic is functionally correct and mirrors the pattern used by Sphinx's LaTeX writer, which checks if 'colwidths-given' is in the table's classes and uses fixed-width column specs in that case. However, the unnecessary comparison should be removed for clarity:

Suggested simplification

  def visit_tgroup(self, node: nodes.tgroup):
      # Only use fixed widths if explicitly specified.
      table_node = node.parent
      colwidths_given = 'colwidths-given' in table_node.get('classes', [])

      cols = []
      for colspec in node.findall(nodes.colspec):
-         if colwidths_given and colspec != "auto":
+         if colwidths_given:
              cols.append(f"{colspec['colwidth']}fr")
          else:
              cols.append("auto")

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/rst2typst/writer.py` around lines 542 - 554, In the visit_tgroup method,
the condition on line 549 compares the colspec node object directly to the
string "auto", which will always be True and makes the logic confusing. Replace
the comparison `colspec != "auto"` with `colspec['colwidth'] != "auto"` to
properly check the colwidth attribute value against the string literal, ensuring
the code correctly applies fixed-width columns only when both colwidths_given is
True and the specific column width is not "auto".

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/rst2typst/writer.py`:
- Around line 542-554: In the visit_tgroup method, the condition on line 549
compares the colspec node object directly to the string "auto", which will
always be True and makes the logic confusing. Replace the comparison `colspec !=
"auto"` with `colspec['colwidth'] != "auto"` to properly check the colwidth
attribute value against the string literal, ensuring the code correctly applies
fixed-width columns only when both colwidths_given is True and the specific
column width is not "auto".

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: f3294a6c-65e7-4122-b548-ca84f697e2a5

📥 Commits

Reviewing files that changed from the base of the PR and between 9e00dfd and 3afda5f.

📒 Files selected for processing (6)

• docs/spec/tables/grid-table.typ.txt
• docs/spec/tables/index.rst
• docs/spec/tables/list-table-autolayout.rst.txt
• docs/spec/tables/list-table-autolayout.typ.txt
• docs/spec/tables/simple-table.typ.txt
• src/rst2typst/writer.py

[imphil]

I think our friend Code Rabbit has a point in #20 (review):

Did you mean to write colspec['colwidth'] == "auto" in the original code to allow users to specify "auto" as width explicitly? The code doesn't look like it ever did that, and I couldn't find similar behavior in the Sphinx LaTex writer either.

[imphil]

I had a closer look at the docutils spec at https://www.docutils.org/docs/ref/rst/directives.html and I think I now know what the original implementation intended :-) I added a couple more unit tests for widths: auto and simplified the code for that case.

I learned: Mixing explicit column widths with auto width isn't supported, so you cannot write something like that widths: 10 auto 32.

[imphil]

@CodeRabbit review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[attakei]

Thank you!