Furo Sphinx Theme

Warnings

• breaking Furo frequently updates its minimum supported Sphinx version. Using an older Sphinx installation may lead to build failures or rendering issues.
  Fix: Ensure your Sphinx installation meets Furo's current requirements. Update Sphinx: `pip install -U sphinx`.
• gotcha Customizing Furo is done via the `html_theme_options` dictionary in `conf.py`. Incorrect option names, unexpected value types, or invalid paths can lead to silent failures or unexpected theme behavior.
  Fix: Refer to the official Furo documentation's 'Customisation' section for a complete list of available `html_theme_options` and their expected values. Validate your `conf.py` settings carefully.
• gotcha Furo is designed for a clean, minimalist aesthetic. While highly customizable through theme options, achieving extensive visual changes that deviate significantly from its base design might require deep overrides of CSS/JavaScript, which can be more complex than expected for users new to Sphinx's asset pipeline.
  Fix: For minor tweaks, utilize `html_theme_options`. For significant visual overhauls, be prepared to explore Sphinx's `html_css_files` and `html_js_files` options, potentially alongside custom SASS compilation, as detailed in advanced Sphinx theme documentation.

Install

• pip install furo Install Furo

Imports

• Theme activation

  html_theme = 'furo' # in conf.py

  Furo is a Sphinx theme, not a standard Python library meant for direct import in user Python code. It is activated via the `conf.py` configuration file.

Quickstart

This quickstart guides you through setting up a basic Sphinx project and enabling the Furo theme. Ensure Sphinx is installed, then create or update your `conf.py` to specify `html_theme = 'furo'` and optionally configure theme options.

# 1. Install Furo and Sphinx
# pip install furo sphinx

# 2. Create a Sphinx project (if you haven't already)
# sphinx-quickstart # Follow prompts, e.g., 'y' for separate build/source dirs

# 3. Edit your conf.py file
# Open docs/conf.py (or your source directory's conf.py)
# Find or add the following line:

# conf.py example snippet:

# -- Project information -----------------------------------------------------
project = 'My Awesome Project'
copyright = '2023, Your Name'
author = 'Your Name'
release = '0.1.0'

# -- General configuration ---------------------------------------------------
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.viewcode',
]

# -- Options for HTML output -------------------------------------------------
html_theme = 'furo'

html_theme_options = {
    "navigation_with_keys": True,
    "sidebar_hide_name": True,
}

# 4. Build your documentation (from the docs directory)
# make html
# Open _build/html/index.html in your browser