Modifying content width of the Sphinx theme 'Read the Docs'

Question

I am using \'Read the Docs\' Sphinx theme for my documentation. In the original theme, given below

http://read-the-docs.readthedocs.org/en/latest/theme.html

Answer 1

The solutions here are somewhat hackish. If you want to include the style, and have a css override and have it work on RTD you will want something like this.

on_rtd = os.environ.get('READTHEDOCS', None) == 'True'

if not on_rtd:  # only import and set the theme if we're building docs locally
  import sphinx_rtd_theme
  html_theme = 'sphinx_rtd_theme'
  html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
  html_style = 'css/custom.css'
else:
  html_context = { 
    'css_files': [
        'https://media.readthedocs.org/css/sphinx_rtd_theme.css',
        'https://media.readthedocs.org/css/readthedocs-doc-embed.css',
        '_static/css/custom.css',
    ],  
  }   

I have tested this myself and it appears to work locally and on RTD. Largely plagiarized from https://blog.deimos.fr/2014/10/02/sphinxdoc-and-readthedocs-theme-tricks-2/

Answer 2

To make the ReadTheDocs theme use the entire width of your screen you can modify the theme.css file, removing the max-width: 800px; property from the wy-nav-content class definition, like so:

.wy-nav-content {
    padding: 1.618em 3.236em;
    height: 100%;
    /* max-width: 800px; */
    margin: auto;
}

---

Some Notes

• Source of theme.css is here:

  https://github.com/rtfd/readthedocs.org/blob/master/media/css/sphinx_rtd_theme.css

• On your filesystem it will be in (assuming you've run:pip install sphinx_rtd_theme):

  lib/python2.7/site-packages/sphinx_rtd_theme/static/css/theme.css

• To find the absolute path of theme.css on Linux/Mac you can run this on the command line (assuming you have set your $PYTHONPATH environment variable):

  for p in `echo $PYTHONPATH | tr ":" "\n"`; do 
      find $p -type f -name 'theme.css' | grep sphinx_rtd_theme
  done
  

• The theme.css file will be minified so you can use a tool like http://unminify.com to make it easier to read.

---

The results:

Before:

After:

Answer 3

Another option is to create a stylesheet in source/_static with just the css you want, e.g.

.wy-nav-content {
    max-width: none;
}

or

.wy-nav-content {
    max-width: 1200px !important;
}

Make sure the directory is referenced in source/conf.py - I believe by default there's a line to do this, i.e.

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

Then create a custom layout in source/_templates/layout.html and do something like this to include your stylesheet

{% extends "!layout.html" %}
{% block extrahead %}
    <link href="{{ pathto("_static/style.css", True) }}" rel="stylesheet" type="text/css">
{% endblock %}

Assuming you called your stylesheet style.css

Answer 4

For 'classic' Theme, The solution is as simple and as clean as :

# Add/Update "html_theme_options" like this on your conf.py
html_theme_options = {'body_max_width': '70%'}

Adapt the percentage to your taste.

Reference from sphinx: body_max_width (int or str): Maximal width of the document body. This can be an int, which is interpreted as pixels or a valid CSS dimension string such as ‘70em’ or ‘50%’. Use ‘none’ if you don’t want a width limit. Defaults may depend on the theme (often 800px).

Answer 5

The HTML option added in Sphinx 1.8.0b1 (released Sep 2018) simplifies the process. The recommendation in Read The Docs Documentation is adding custom css to the theme via the html_css_files option in conf.py.

html_css_files = [
    'custom.css',
]

Put the custom.css in the html static path folder (Default is _static folder).

Content of custom.css:

.wy-nav-content {
    max-width: 75% !important;
}

Answer 6

Just in case someone is still searching for a simple answer... combining the ideas from https://samnicholls.net/2016/06/15/how-to-sphinx-readthedocs/ and the above suggestions i found that the most easy way of getting a custom window-width is the following:

in conf.py add a function that adds your custom stylesheet (just add the following lines):

def setup(app):
    app.add_css_file('my_theme.css')

and then create a file called my_theme.css in the _static folder that simply contains the following lines:

.wy-nav-content {
max-width: 1200px !important;
}