Controlling the Width of a Table With Read-the-Docs
"But I don’t want a scrollbar!!"
Read The Docs is a great platform for creating documentation that lets you focus on content rather
than complex markup syntax or making it searchable. One of the elements you might want to put in
your documentation is a table. There are different ways to create a table, and one that I like
Consider the following markup:
1.. list-table:: Comparison 2 :widths: 20 10 10 15 20 3 :header-rows: 1 4 5 * - Platform 6 - Self-Contained? 7 - Cost 8 - Flexibility 9 - Description 10 * - Raspberry Pi 11 - No 12 - $30 13 - Limitless 14 - Mini computer board with GPIO pins for interfacing and experimentation. 15 * - Lego Mindstorms 16 - Yes 17 - $350 18 - Medium 19 - Lego robotics sytem with motors and sensors. Build a robot, then write logic to move it around and do stuff.
The markup above creates the following table as shown in the following image; specifically note the horizontal scrollbar at the bottom:
Often, there is good content to the right of what you can initially see, but there is no built-in option to keep the contents of the table directly in the viewing area.
Custom CSS to the rescue!
A little bit of custom CSS will enable what we’re after, but there are some specific steps to get the custom CSS into a Read The Docs project.
Create the custom CSS file
If you’ve created a Read The Docs project using
sphinx-quickstart, you probably have a
_static directory in your project folder. The image below shows the folder structure and the CSS code that you should add to the file. The class name of
tight-table can be anything you want, but we will use it again later so keep track of it if you change it.
Get the custom CSS into the built output
Just putting the CSS there will not allow you to reference the class yet — it needs to be copied to the HTML built output that gets created when you “make” the project.
To do this, add the following code to you
1def setup(app): 2 app.add_stylesheet('css/custom.css')
The path in the above code is relative to the
_static folder in your doc project. The
setup function is something that the Read The Docs build process will look for and run automatically if it’s available.
Reference the class
Back in the original document with your table, you can now simply reference the class as shown in the code snippet below.
1.. list-table:: Comparison 2 :widths: 20 10 10 15 20 3 :header-rows: 1 4 :class: tight-table 5 6 * - Platform 7 . . .
Yay! No more scrollbar!
When you build the project with all of these changes in place, you now get a table that looks as shown below — the content is all visible without scrolling!!!
If you want to know more about Read The Docs, from anything from Sphinx tips, hosting the project on your own or inside ReadTheDocs.org, the Git workflow that goes along with it, versioning, and more, I encourage you to check out my Pluralsight course titled Build or Contribute to Documentation with a Git-based Workflow.