Skip to main content

Some tricks and hacks with Sphinx

This is a (hopefully!) growing collection of tricks and hacks that I have come across working with RST documents, Sphinx and Read the Docs.

Vim and RST

I love Vim (actually, MacVim), and as soon as I started working with RST documents for the first time, I hoped to find a nice plug-in to speed up my editing.

Of course, someone had already thought about that... Enter Riv!

Riv is a great plug-in, with many shortcuts to make your life easier when dealing with RST files. In my opinion, the best thing about Riv is how it handles table creation. You create cells by simply pressing tab, and when you modify the content, the table automatically reshapes when you exit the edit mode.

A few shortcuts for you:

  • tab: move to the next cell
  • option + enter: create the header row
  • control + enter: create a new regular row
Create RST tables with Riv plug-in for MacVim

Create tables with Riv.

If you try Riv, don't forget to install InstantRst as well. This will enable a live preview in the browser, as you edit your document.

Tables in Sphinx

Tables in Sphinx can be a very frustrating thing. Sometimes you have a large table that is difficult to render with the RST syntax; in other cases, the table looks good in the HTML page but awful in the PDF output.

For those cases, I have created a short tutorial about tables with Sphinx.

One of the best options, in my option, is to work with CSV tables. You can create your table in a spreadsheet, without the need to worry about the proper formatting in RST. To take care of the PDF output for those long tables that won't fit on a single page, you can use the longtable class. Then, with the tabularcolumns directive, you can control the width of the columns in your PDF.

This is a sample code snippet to render a table from a CSV file. Check the result in the tutorial.

.. tabularcolumns:: |p{1cm}|p{7cm}|

.. csv-table:: Caption of the figure
   :file: path-to-the/file.csv
   :header-rows: 1
   :class: longtable
   :widths: 1 1

This approach also works if you use a grid table instead of a CSV table, with the proper changes.

Convert HTML tables to RST

Speaking of tables, if you start from a table in HTML, you can use DashTable to convert it to RST. This tool will produce for you a nice grid table that you can easily copy and paste in your RST document.

Break numbered lists

Whenever you start a line with 1. Something..., Sphinx produces a numbered list. Sometimes, however, this is not the behaviour you would like to achieve.

To break the numbered list, you can just add a backslash after the number, like this: 1\. Something.... This is enough for Sphinx to treat the line as a normal sentence.