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

the content or main layout width is designed to be mobile friendly. However, for my project I would like this to be a bit more wide. I do not know HTML and hence would appreciate if any one could give me some clues to increase the content (layout) width.

In 2019, it is as simple as adding the required css via html_css_files option. Please see my answer https://stackoverflow.com/a/57840173/466066 — Jose Cherian, Sep 08 '19 at 08:08

score 54 · Accepted Answer · edited Oct 06 '16 at 12:47

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

This was the solution I used. Is probably the best option if you are using ReadTheDocs for your build. — Chris Harrington, Aug 20 '16 at 23:37

score 26 · Answer 2 · edited Feb 02 '22 at 14:38

In case someone is searching for a simpler answer... combining the ideas from https://samnicholls.net/2016/06/15/how-to-sphinx-readthedocs/ and the above suggestions, I found the easiest way of getting a custom window-width is the following:

In conf.py, add a function that adds a custom stylesheet:
```
def setup(app):
    app.add_css_file('my_theme.css')
```
In conf.py, state/adjust:
```
html_static_path = ['_static'] 
```
Create a _static folder/directory if it doesn't exist.
Create a file called my_theme.css in the _static folder that contains the lines:
```
.wy-nav-content {
    max-width: 1200px !important;
}
```

Simplest choice and it worked locally and on gitlab pages. – Asta86 Nov 20 '18 at 04:29 — Asta86, Nov 20 '18 at 04:29

score 18 · Answer 3 · edited Jun 20 '20 at 09:12

First of all I must say, that during my sphinx quickstart I chose the option of separate folder for my sources and for my build.

It's a 3 steps process:

1. Create a document for your styles:

Where?

In the same directory where my conf.py lives, (in my case source), I created a folder for my custom static files (stylesheets, javascripts). I called it custom.
Inside it I created a subfolder for my stylesheets: source/custom/css.
In this subfolder I'm gonna create my custom styles: source/custom/css/my_theme.css.

2. Telling sphinx about it

Now we have to tell sphinx to spit this document inside build/_static/css, the same directory where is the stylesheet included in the Read The Documents theme. We do that adding the following line to conf.py:

html_static_path = ['custom']       # Directory for static files.

Done. Now, if we build, we will have the RTD styles (theme.css), and our custom my_theme.css in the same directory, build/_static/css.

3. Selecting our custom theme

Now we are gonna tell sphinx to use our custom my_theme.css, instead of the RTD one. We do that adding this line in conf.py:

html_style = 'css/my_theme.css'     # Choosing my custom theme.

In our custom stylesheet, the first line should import the styles of theme.css with @import url("theme.css");.

And we are ready to start overwriting styles.

UPDATE: THERE IS AN EVEN SIMPLER WAY.

1. Put your customizations inside `source/_static/css/my_theme.css`.

In your custom stylesheet, the first line should import the styles of theme.css with @import url("theme.css");.

This way, you don't have to worry about messing up the default styles, if your custom stylesheet doesn't work, delete and start again.

2. Add the following line in `conf.py`:

html_style = 'css/my_theme.css'

thanks for pointing @import. It's the least-hackish way to add new stylesheet to RTD theme — Alleo, Aug 11 '15 at 15:45
this only works in local builds. If I publish my docs to the website, it won't load the .css — ffleandro, Aug 13 '15 at 15:22
Note: This will *not* work with a hyphen in the file (i.e. my-theme.css). — Hari, Apr 29 '21 at 00:10

score 17 · Answer 4 · edited Feb 14 '20 at 03:32

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;
}

score 7 · Answer 5 · answered Oct 01 '15 at 23:40

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/

Yahya Yahyaoui · Answer 6 · 2019-03-02T18:32:34.373

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).

score 5 · Answer 7 · answered Jun 12 '20 at 06:27

5

source\conf.py

html_theme = 'sphinx_rtd_theme'
html_style = 'css/my_theme.css'

source\_static\css\my_theme.css

@import url("theme.css");

.wy-nav-content {
    max-width: 90%;
}

That will be 90% width of your monitor.

answered Jun 12 '20 at 06:27

kucer

66
1
4

1

This helped! I was trying to use default alabaster theme and nothing I did could make the display wider. As soon as I followed this example and changed theme to 'sphinx_rtd_theme', then the result was both much nicer to look at and used whole browser width. Whew. – pauljohn32 Aug 24 '20 at 16:32

score 3 · Answer 8 · answered Apr 04 '15 at 18:55

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:

Unmodified readthedocs theme

After:

Modified readthedocs theme

score 1 · Answer 9 · answered Apr 29 '14 at 19:59

I would modify this in the css. You should search for the file theme.css (it is in the read-the-doc sources at "sphinx_rtd_theme/static/css/theme.css").

Make a copy of that file and put it in your sphinx _static dir. In that css file you can make all the layout changes that you need. (You might have to read a bit on css files if you have never worked with that.)

Hope this helps.

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

9 Answers9

1. Create a document for your styles:

2. Telling sphinx about it

3. Selecting our custom theme

UPDATE: THERE IS AN EVEN SIMPLER WAY.

1. Put your customizations inside `source/_static/css/my_theme.css`.

2. Add the following line in `conf.py`:

Some Notes

The results:

Before:

After:

Linked

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

9 Answers9

1. Create a document for your styles:

2. Telling sphinx about it

3. Selecting our custom theme

UPDATE: THERE IS AN EVEN SIMPLER WAY.

1. Put your customizations inside source/_static/css/my_theme.css.

2. Add the following line in conf.py:

Some Notes

The results:

Before:

After:

Linked

1. Put your customizations inside `source/_static/css/my_theme.css`.

2. Add the following line in `conf.py`: