57

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

Read the Docs Sphinx Theme

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.

3
  • 3
    In 2019, it is as simple as adding the required css via html_css_files option. Please see my answer stackoverflow.com/a/57840173/466066 Sep 8, 2019 at 8:08
  • @hypersonics The link is broken. Perhaps you could update it? Aug 15, 2022 at 15:55
  • 1
    @JamesHirschorn I have just updated. Hope it helps. Feb 24 at 22:41

10 Answers 10

63

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

1
  • 3
    This was the solution I used. Is probably the best option if you are using ReadTheDocs for your build. Aug 20, 2016 at 23:37
31

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:

  1. In conf.py, add a function that adds a custom stylesheet:

    def setup(app):
        app.add_css_file('my_theme.css')
    
  2. In conf.py, state/adjust:

    html_static_path = ['_static'] 
    
  3. Create a _static folder/directory if it doesn't exist.

  4. Create a file called my_theme.css in the _static folder that contains the lines:

    .wy-nav-content {
        max-width: 1200px !important;
    }
    
1
  • Simplest choice and it worked locally and on gitlab pages.
    – Asta86
    Nov 20, 2018 at 4:29
24

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;
}
1
  • 1
    This is the simplest solution. Just note that the name of the style is wy-nav-content, not my-nav-content, as I first thought.
    – Asaga
    Jul 12, 2022 at 15:34
18

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?

  1. 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.
  2. Inside it I created a subfolder for my stylesheets: source/custom/css.
  3. 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' 
3
  • 1
    thanks for pointing @import. It's the least-hackish way to add new stylesheet to RTD theme
    – Alleo
    Aug 11, 2015 at 15:45
  • 2
    this only works in local builds. If I publish my docs to the website, it won't load the .css
    – ffleandro
    Aug 13, 2015 at 15:22
  • Note: This will not work with a hyphen in the file (i.e. my-theme.css).
    – Hari
    Apr 29, 2021 at 0:10
7

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/

7
  1. source\conf.py
html_theme = 'sphinx_rtd_theme'
html_style = 'css/my_theme.css'
  1. source\_static\css\my_theme.css
@import url("theme.css");

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

That will be 90% width of your monitor.

1
  • 2
    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, 2020 at 16:32
7

I found myself repeating this customization on multiple projects I've worked on (based on the great answers here, of course 😃 ).

So I made an extension just for that, the usage is as follows:

pip install sphinx-rtd-size

And in the conf.py:

    extensions = [
        ...
        'sphinx_rtd_size',
    ]
    
    sphinx_rtd_size_width = "90%"

Hoping this might simplify things for future users...

You can checkout the pypi page and the github repository.

Edit 1:

Clarification - This extension is only relevant for the theme "sphinx_rtd_theme".

6
  • Thank you!! The straightforward answer we all needed. Works like a charm Sep 21, 2022 at 5:55
  • I do not know if you have the same issue, but when using the viewcode extension, the source code is not displayed using the requested size width. Jan 17 at 16:11
  • I like this idea, but the output doesn't work as I expected, any thing I can verify in final html ` <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />` ?
    – Larry Cai
    Feb 23 at 15:21
  • aha, better to mention, it use theme 'sphinx_rtd_theme' (i tried with default alabaster, which doesn't work), now I am happy
    – Larry Cai
    Feb 23 at 15:26
  • after installing, i'm getting exception: No module named 'sphinx_rtd_size' May 18 at 12:08
6

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

0
4

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


The results:

Before:

Unmodified readthedocs theme

After:

Modified readthedocs theme

1

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.

Your Answer

Reminder: Answers generated by Artificial Intelligence tools are not allowed on Stack Overflow. Learn more

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.