“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
is the list-table format.
Consider the following markup:
.. list-table:: Comparison :widths: 20 10 10 15 20 :header-rows: 1 * - Platform - Self-Contained? - Cost - Flexibility - Description * - Raspberry Pi - No - $30 - Limitless - Mini computer board with GPIO pins for interfacing and experimentation. * - Lego Mindstorms - Yes - $350 - Medium - Lego robotics sytem with motors and sensors. Build a robot, then write logic to move it around and do stuff.
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 conf.py file:
def setup(app): 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.
.. list-table:: Comparison :widths: 20 10 10 15 20 :header-rows: 1 :class: tight-table * - Platform
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”.