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

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.

Hurter

In 2019, it is as simple as adding the required css via html_css_files option. Please see my answer https://mcmap.net/q/139143/-modifying-content-width-of-the-sphinx-theme-39-read-the-docs-39 – Iulus

@Hurter The link is broken. Perhaps you could update it? – Poleaxe

@JamesHirschorn I have just updated. Hope it helps. – Hurter

Answer 1

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

Glomerule

This was the solution I used. Is probably the best option if you are using ReadTheDocs for your build. – Harkness

Answer 2

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

Guyton

Simplest choice and it worked locally and on gitlab pages. – Dorindadorine

Answer 3

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

Iulus

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. – Cantabile

Answer 4

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' 

Fingerbreadth

thanks for pointing @import. It's the least-hackish way to add new stylesheet to RTD theme – Aftereffect

this only works in local builds. If I publish my docs to the website, it won't load the .css – Hexapartite

Note: This will not work with a hyphen in the file (i.e. my-theme.css). – Late

Answer 5

1. source\conf.py

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

2. source\_static\css\my_theme.css

@import url("theme.css");

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

That will be 90% width of your monitor.

Whitmer

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. – Yseulta

Answer 6

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/

Toscana

Answer 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".

Inconclusive

Thank you!! The straightforward answer we all needed. Works like a charm – Fanaticize

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. – Blackleg

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" />` ? – Physics

aha, better to mention, it use theme 'sphinx_rtd_theme' (i tried with default alabaster, which doesn't work), now I am happy – Physics

after installing, i'm getting exception: No module named 'sphinx_rtd_size' – Succory

Please create an issue in the linked github page with steps to reproduce (including sphinx, rtd packages versions used) and I'll try to help resolve this issue. – Inconclusive

Answer 8

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

Dumbarton

Answer 9

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:

Nyctophobia

Answer 10

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.

Assort

Answer 11

I think sphinx has now gave the expanded options for the theme Now you can modify the conf.py script itself to get the max width

-- Options for HTML output --

The theme to use for HTML and HTML Help pages. See the documentation for a list of builtin themes. html_theme = 'default'

Theme options are theme-specific and customize the look and feel of a theme further. For a list of options available for each theme, see the documentation.

html_theme_options = {'body_max_width': None} # Use the full width of the window

Dalmatia