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

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.

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

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

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

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?
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'

Answer 5

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 6

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.

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.

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

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:

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.