How to right-align columns content in reStructuredText simple tables?

Question

I'm editing the documentation for a project of mine using Sphinx, which in turn uses reStructuredText as markup language.

I have a simple table (as opposed to grid table) in which the rightmost column reports contains numbers that I would like to right-align, but I couldn't find how to achieve that.

============  =====================
Event               Score variation
============  =====================
Event 1                        +100
Event 2                         -25
Event 3                        -400
============  =====================

I would be happy to switch to a grid table if this would allow me to solve the problem.

Bonnes

reStructuredText doesn't support right alignment of anything. You're be stuck with styling it manually, I think. Good question, though. +1 – Panlogism

@Bonnes What Python version do you use ? And what kind of columns are there in your files: always numbers in the second one ?, always letters at the beginning in first column ?, what kind of separation between first and second column (several blanks ? what minimum number of blanks ? tabs ? given widths ?...) – Disaffiliate

@Disaffiliate - Mmm... from the kind of questions, I would guess you misunderstood me... but here are the answers, nevertheless: 2.7.1+ | depends from what .rst file and what table in the file | depends | several blanks | 1. – Bonnes

@Bonnes reStructuredText not being supporting the feature you want, according to Chris Morgan, I thought that you then must consider to make a special treatment of each file, after its creation, with the help of builtin string's methods or if needed regexes. But the possibility I didn't understand the problem is quite realistic. Do you mean that you would like that the right-alignement should be coded in some special tag or other feature of the reStructuredText document type ? – Disaffiliate

Answer 1

Sadly I don't think rst offers that ability... the table styling options are rather limited. That said, if you're rendering to HTML, you could add a custom stylesheet with a css rule such as:

table.right-align-right-col td:last-child {
    text-align: right
}

and then add the directive:

.. rst-class:: right-align-right-col

right above your table in the rst file. It's clunky, but it should work.

---

update 2013-2-6: I've since needed to accomplish this myself, and came up with a more permanent solution. The cloud_sptheme.ext.table_styling Sphinx extension adds directives for doing column alignment, per-column css classes, and number of other table styling tricks. Despite being packaged as part of the "cloud" Sphinx theme, it should work with any Sphinx theme.

Watson

Thank you Eli. I finally chose a theme (agogo) that has ugly tables, so - while I will work my way to improve that, I will use your snippet too. – Bonnes

Answer 2

While it appears that ReST doesn't actually support cell content alignment, you can actually use line-blocks within your cell to enforce preservation of whitespace to effectively pad your cell's content.

You'll have to use some of the unicode-whitespace characters (e.g. U+2001 - EM QUAD) and have them preceded by a normal space character (U+0020) i.e. U+0020U+2001Your String to stop the ReST parser complaining about malformed tables and unterminated substitution references, etc.

+--------+---------+
| String | Num     |
+========+=========+
| foo    ||   12.00|   # second cell's content is actually |<U+0020><U+2001>12.00
+--------+---------+
| bar    ||    3.01|
+--------+---------+
| baz    ||    4.99|
+--------+---------+
| moo    ||   15.99|
+--------+---------+
| quux   ||   33.49|
+--------+---------+
| foo    ||   20.00|
+--------+---------+
| bar    ||  100.00|
+--------+---------+

Tables like the above start to look a bit awkward and are awkward to maintain but the approach gets the job done. It also goes without saying, you'll need to both edit and generate UTF-8 output. While rst2html.py treats this well, I'm not sure how sphinx deals with this and if it can, whether the alignment remains when generating non-HTML documents.

Albion

Thank you for this suggestion. :) I find it conceptually interesting, but I believe it would be practically very hard to maintain documentation where invisible non-space whitespace is relevant... – Bonnes

Absolute madness. Nobody do this in the real world, please. The new guy will have no idea why everything is suddenly ugly, it's Friday night, it's all his fault, and the weekend ahead is now looking grim indeed. – Phenazine

Answer 3

You can use the centered directive. I've included an example below:

+------+-----------+------------+--------+------+------+
| Type |  .. centered:: -payload-        | crcL | crcH |
+------+-----------+------------+--------+------+------+
| Type | subType   | obj/access | -data- | crcL | crcH |
+------+-----------+------------+--------+------+------+

Here's what that looks like in HTML

Starveling

Just realized the title is for right-aligned, not centered... whoops – Starveling

Solves my problem thought! Thanks! – Telegraphy

Answer 4

My approach is a bit of sed on the TeX file generated by Docutils. The idea is to replace the table declaration with something that fits your needs.

Docutils produce something like that :

\begin{longtable*}[c]{p{0.086\DUtablewidth}p{0.290\DUtablewidth}}

Imagine you want to right-align the second column.You may want to replace this with :

\begin{longtable*}[c]{lr}

But you lose the ability to control the width of the cells. What we need here is to declare 2 \newcolumntype, one for the right-align (x) and one for the left-align (y):

\newcolumntype{x}[1]{% 
>{\raggedleft\hspace{0pt}}p{#1}}% 
\newcolumntype{y}[1]{% 
>{\raggedright\hspace{0pt}}p{#1}}% 

And use them in the table declaration:

\begin{longtable*}[c]{y{7.5cm}x{2cm}}

The \\ newline must also be replaced with a \tabularnewline.

I put everything in a script file because I am on OSX and the version of sed shipped does not support newline substitution with \n (that sucks when you are in a Makefile).

The bottom-line

On OSX/BSD:

sed -E -f fix_table.sed < source.tex > destination.tex

with fix_table.sed:

s/\\begin{longtable\*}.*/\\newcolumntype{x}[1]{% \
>{\\raggedleft\\hspace{0pt}}p{#1}}% \
\\newcolumntype{y}[1]{% \
>{\\raggedright\\hspace{0pt}}p{#1}}% \
\\begin{longtable*}[c]{y{7.5cm}x{2cm}}/
s/\\\\/\\tabularnewline/

This is a bit harsh but there is no workaround that really works at the RestructuredText level.

http://en.wikibooks.org/wiki/LaTeX/Tables

http://texblog.org/2008/05/07/fwd-equal-cell-width-right-and-centre-aligned-content/

Poynter

Thank you. Myself I'm on GNU/Linux, yet +1 for the clear and useful explanation! :) – Bonnes

This should work on GNU/Linux without the -E modifier. And you can use \n in Sed instead of real newlines. – Poynter

Answer 5

As of Docutils 0.13 (late 2016), the table directive supports an align option.

.. table::
   :align: right

   ======== ==== ==== ==== ==== ==== ==== ==== ==== ==== 
   4 \\ 9    0    1    2    3    4    5    6    7    8  
   ======== ==== ==== ==== ==== ==== ==== ==== ==== ==== 
   0         0   28   20   12    4   32   24   16    8  
   -------- ---- ---- ---- ---- ---- ---- ---- ---- ---- 
   1         9    1   29   21   13    5   33   25   17  
   -------- ---- ---- ---- ---- ---- ---- ---- ---- ---- 
   2        18   10    2   30   22   14    6   34   26  
   -------- ---- ---- ---- ---- ---- ---- ---- ---- ---- 
   3        27   19   11    3   31   23   15    7   35  
   ======== ==== ==== ==== ==== ==== ==== ==== ==== ==== 

Your stylesheet will need to support the .align-right class

Pyroxene

This right-aligns the entire table, doesn't it? The question is about right-aligning the values in the rightmost column. – Rex

Nope. It right aligns the values in each cell, but the table is left aligned. See the table rendered at georgevreilly.com/blog/2019/09/15/use-for-octal.html – Pyroxene

I am referring to the default behaviour of Sphinx and Docutils, without any CSS customizations. I tried the "read_the_docs", "nature" and "classic" themes. With the :align: right option, the whole table is right-aligned, not the values in the cells. – Rex