How to Set Up Custom Styles for Restructuredtext, Sphinx, Readthedocs, etc.

How do I set up custom styles for reStructuredText, Sphinx, ReadTheDocs, etc.?

Edit: as of 2021 the following answer is outdated, please use html_css_files = [] in your conf.py instead of using the application API after version 1.8 (current Sphinx version at time of writing is 4.1.1). The add_stylesheet option below has been renamed add_css_file in version 1.8, and seems more intended for Sphinx extension developers.

Assumptions

Your RTD doc set has something like the following structure:

• (root path)
  
  • (some other stuff not germane to this discussion)
  • _static/
  • _templates/
  • conf.py

You're also building locally using sphinx-build or sphinx-autobuild using the default theme, but your deployed server might use the sphinx-rtd-theme instead.

Use Case: Hatnotes

For this illustration, I'm going to show how to create custom styling for "hatnotes", a concept which is prevalent in MediaWiki docs and which corresponds roughly to the admonition construct in RST. You can apply what's shown here to create any custom CSS and include it in your doc set.

Step 1: Create Custom CSS

The custom CSS file should go somewhere under the _static/ directory, as that's where the build process and scripts will find it. I would encourage a css/ subdirectory, since you might have other customizations to add, like JavaScript files.

Create your custom CSS file and put it in this directory. Write your style specifications as an overlay to whatever might already exist in the theme you'll be using in the build. Also don't assume anything about whether your style will override an existing style in the theme, as you can't guarantee when your styles will be added in relation to the default ones.

Here's my custom CSS for hatnotes. I saved this at _static/css/hatnotes.css.

.hatnote
{
    border-color: #c8c8c8 ;
    border-style: solid ;
    border-width: 1px ;
    font-size: x-small ;
    font-style: italic ;
    margin-left: auto ;
    margin-right: auto ;
    padding: 3px 2em ;
}
.hatnote-gray { background-color: #e8e8e8 ; color: #000000 ; }
.hatnote-yellow { background-color: #ffffe8 ; color: #000000 ; }
.hatnote-red { background-color: #ffe8e8 ; color: #000000 ; }
.hatnote-icon { height: 16px ; width: 16px ; }

Step 2: Add Styles to Templates

For the default theme, it is sufficient to create a template that overrides the default layout.html to add your custom CSS to the layout. Use of templates is well documented at sphinxdoc.org. In your override template, simply set the css-files variable (an array) with an appended list of your custom CSS files.

Here is my template which adds the hatnotes CSS. I saved this as _templates/layout.html.

{% extends "!layout.html" %}
{% set css_files = css_files + [ "_static/css/hatnotes.css" ] %}

That's all you need to do for the default theme. For the Sphinx/RTD theme, there's an additional step, where you…

Step 3: Add Stylesheets to the Theme

For the Sphinx/RTD theme, your template will be ignored. Instead of using the template mechanism, you have to add a function to your conf.py file which adds the CSS file to the app's theme. Somewhere near where your conf file sets the html_theme attribute, add something like the following:

def setup(app):
  app.add_stylesheet( "css/hatnotes.css" )

Note that, this time, there's no _static/ at the front of the path; the add_stylesheet() function assumes that part of the path.

Finishing the Use Case

Now that you've set up your custom styles for both the default theme and the Sphinx/RTD theme, you can actually use them in your doc.

Following the usual paradigm of defining stock hatnotes as "templates" in MediaWiki (sorry, not the same as templates in Sphinx and RTD), I set up an includes/ directory where all my hatnotes would be stored.

Here's how to construct a hatnote with the custom style information. This file is includes/hatnotes/stub-article.rst.

.. container:: hatnote hatnote-gray

   |stub| This article is a stub. Please improve the docs by expanding it.

.. |stub| image:: /images/icons/stub.png
          :class: hatnote-icon

Here we set up our "stub" hatnote to have the default hatnote styling, the gray background, and use a "stub" icon as the inline image, with the hatnote-icon style applied to that image.

Now we can use the file as an included resource in a document.

Foo Article
===========

.. include:: /includes/hatnotes/stub-article.rst

Blah blah I haven't written this article yet.

Whether you're using the local default theme or the Sphinx/RTD theme, the hatnote will be rendered with the styles you added by setting up the _templates/layout.html template and the conf.py script to both include the custom CSS file you put under the _static/ directory.

End State

Your doc repository now has this stuff in it:

• (root path)
  
  • _static/
    
    • css/
      
      • (custom CSS files…)
  • _templates/
    
    • layout.html — (adds your custom CSS to the default layout)
  • conf.py — (with new function to add custom CSS to app's theme)

How to add custom css file to Sphinx?

A simpler way is to add this to your conf.py:

def setup(app):
    app.add_css_file('css/custom.css')  # may also be an URL

Then put the file into the _static/css/ folder.

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

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

Make the heading levels of documents automatically dependent of the depth's levels of the (sub(sub(...)))folders they belong to

The style applied to the toctree entries is dependent on the theme you are using. The theme's CSS will apply a style to the entries that Sphinx translated into <ul> and <li> depending both on their place within the "document hierarchy" given how you chain the toctrees and how your section structure in the individual .rst files is organized.

For example, inspect the HTML elements Sphinx generates. The toctree will be a div class="toctree-wrapper compound" with each level of sections being named <li class="toctree-l1"> then <li class="toctree-l2">, etc...

One way to achieve what you want would be to surround a given toctree using a .. class:: directive (as show here) and apply a custom style. But that would then impact the style of any other .rst files you want to include as entries in that toctree.

In any case, you will incur in extra work and potentially loose automatism if you refactor your project.

There is also one possible workaround, using the :hidden: option together with the :include: directive. If you declare a hidden toctree before a visible toctree the "document hierarchy" can fix the position of an entry for you in the hierarchy. Afterwards the visible toctree without the :hidden: option will render .rst file entries as a <li> element having a fixed position in the hierarchy. (A thorough example can be seen in this post).

It can be done, but you will be working against the characteristics of the toctree.

The prevalent solution is writing your .rst files and sections depending on how you want the toctree to display. (This approach has all the advantages with the only drawback of putting restrictions on how you write the .rst files). It's probably the preferable solution rather than trying to adapt the CSS styles or using workarounds.

---

EDIT:

What I wrote before is valid, but probably too general. So I'll give one possible solution to the example. If you want the following:

Contents:

    • This a title (foo0)
      ◦ This a title (foo1)
        ▪ This a title (foo2)

A simple option is using a chain of toctrees. You can hide the toctree's that are lower in the document hierarchy if you don't want to see them.

index.rst

.. toctree::
   :maxdepth: 3

   foo0

and in foo0.rst

.. toctree::
   :maxdepth: 3
   :hidden:

   subfolder1/foo1

and in subfolder1/foo1.rst

.. toctree::
   :maxdepth: 3
   :hidden:

   subfolder1/subfolder2/foo2

The result will be as you specified.

Customize sphinxdoc theme

All I wanted is to add ReST strikethrough in my sphinx doc. Here is how I did it:

$ cd my-sphinx-dir
$ mkdir -p theme/static
$ touch theme/theme.conf
$ touch theme/static/style.css

In theme/theme.conf:

[theme]
inherit = default
stylesheet = style.css
pygments_style = pygments.css

(this makes it look like the default theme (l. 2))

In theme/static/style.css:

@import url("default.css"); /* make sure to sync this with the base theme's css filename */

.strike {
    text-decoration: line-through;
}

Then, in your conf.py:

html_theme = 'theme' # use the theme in subdir 'theme'
html_theme_path = ['.'] # make sphinx search for themes in current dir

More here: https://sphinx.readthedocs.io/en/master/theming.html.

(Optional) In global.rst:

.. role:: strike
   :class: strike

and in a example.rst:

.. include:: global.rst

:strike:`This looks like it is outdated.`

How to control image previews for links to readthedocs/ sphinx page?

One of many meta tags available in:

https://github.com/wpilibsuite/sphinxext-opengraph

conf.py

extensions = ['sphinxext.opengraph']

ogp_image = "https://raw.githubusercontent.com/aiqc/aiqc/main/docs/images/aiqc_logo_banner_controlroom.png"

It even has a field for user-defined <meta> tags.

Can't make a bullet list in reStructuredtext (Sphinx/readthedocs) in the format that I want?

It seems to be a bug in the sphinx_rtd_theme which is currently used as the default theme on readthedocs, so you should probably fill an issue at it's github page. In the meantime you can use this workaround:

1. Sample 1

  * ``sub bullet 1``
  * ``sub bullet 2``

2. Sample 2

  * ``sub bullet 1``

The bad thing here is that you have to number your enumerated list by hand, also the indentation of the bullet list is not really correct, but it works and builds documentation without errors with the sphinx_rtd_theme.

Or you can switch to another theme (e.g. default) where this type of markup is parsed correctly.

SphinxRtdTheme undefined after making custom-named fork of sphinx_rtd_theme

It turns out that my theme was being built into a separate version (dev0) than I expected, and thus it was perpetually stuck on a previous version. Updating everything to the current version removes the errors.

---

Related Topics