10. VSCode conf.py file

In VSCode, edit the conf.py file in the docs folder.

10.1. Sphinx extensions

  • A typical extensions list:

extensions = [
    'sphinx_rtd_theme',
    'sphinx_copybutton',
    'sphinx.ext.todo',
    'sphinx.ext.autodoc',
    'sphinx_togglebutton',
    'sphinx_design',
    "sphinx_new_tab_link",
]

10.2. sphinx_rtd_theme

  • Use the sphinx_rtd_theme for html display on the ReadTheDocs website.

  • The Project information section of conf.py should have

import sphinx_rtd_theme

  • Change html_theme = 'alabaster' to html_theme = 'sphinx_rtd_theme'

html_theme = 'sphinx_rtd_theme'

  • Add 'sphinx_rtd_theme' to the extensions list:

extensions = [
    'sphinx_rtd_theme'
]

10.3. sphinx-rtd-theme Theme Options

html_theme_options = {
    'logo_only': False,
    'prev_next_buttons_location': 'both',  # Can be bottom, top, both , or None
    'style_external_links': True,  # True to Add an icon next to external links
    'style_nav_header_background': 'linear-gradient(to right, blueviolet 15%, limegreen 50%, royalblue 80%)',  # blue
    # Toc options
    'collapse_navigation': False,  # False so nav entries have the [+] icons
    'sticky_navigation': False,  # False so the nav does not scroll
    'navigation_depth': 4,  # -1 for no limit
    'includehidden': True,  # displays toctree that are hidden
    'titles_only': False  # False so page subheadings are in the nav.
}

10.4. Custom css

  • Add the code below to the Options for html output section of conf.py to use the custom css in the _static/css/custom.css file.

html_css_files = ['css/custom.css']