Table width fix for Read the Docs Sphinx theme#

The Read the Docs Sphinx theme contains a bug that causes text in table cells not to wrap. This results in very wide tables with horizontal scroll bars.

You can workaround this issue by defining a custom CCS override file.

  1. Change into your documentation directory. This is usually where the index.rst and conf.py files are located:

    $ cd doc
    
  2. If it does not already exist, create a _static directory:

    $ mkdir _static
    
  3. Create a theme_overrides.css file in the _static directory:

    $ touch _static/theme_overrides.css
    
  4. Open the theme_overrides.css file and add the following CSS:

    /* override table width restrictions */
    @media screen and (min-width: 767px) {
    
       .wy-table-responsive table td {
          /* !important prevents the common CSS stylesheets from overriding
             this as on RTD they are loaded after this stylesheet */
          white-space: normal !important;
       }
    
       .wy-table-responsive {
          overflow: visible !important;
       }
    }
    
  5. Open the conf.py file and add the following configuration options:

    html_static_path = ['_static']
    
    html_context = {
        'css_files': [
            '_static/theme_overrides.css',  # override wide tables in RTD theme
            ],
         }
    
  6. Build your documentation using Sphinx and check the tables; cells should now wrap correctly.