10. VSCode conf.py fileο
In VSCode, edit the conf.py
file in the docs folder.
10.1. 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'
tohtml_theme = 'sphinx_rtd_theme'
html_theme = 'sphinx_rtd_theme'
Add
'sphinx_rtd_theme'
to the extensions list:
extensions = [
'sphinx_rtd_theme'
]
10.2. sphinx-rtd-theme Theme Optionsο
See: https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html
Add the code below to
conf.py
with these suggested options:
html_theme_options = {
'logo_only': False,
'display_version': False, # False so doc version not shown
'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-gradientlinear-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.3. Custom cssο
Add the code below to the
Options for HTML output
section ofconf.py
to use the custom css in the_static/css/custom.css
file.
html_css_files = ['css/custom.css']
10.4. Custom logoο
Add the code below to the
Options for HTML output
section ofconf.py
to use the custom logo in the_static/logo.png
file.
html_logo = '_static/logo.png'
Add the code below to the
Options for HTML output
section ofconf.py
to use the custom favicon in the_static/favicon.ico
file.
html_favicon = "_static/favicon.ico"